/*::.
==================================================================================================================================
=================================================¦ Copyright © 2014 Allen Baker ¦=================================================
                                                 +------------------------------+
File:       SourceCodeFileBasicFamily.java
Originator: Allen Baker (2014.06.24 15:26)
LayoutRev:  5
================================================================================================================================== */
package cosmicabyss.com.lib;

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



/*::
======================================================================================================================== *//**
Description
   <BLOCKQUOTE>
      <PRE id="unindent">
         Instances of this class represent a xxx.

         Salient characteristics of xxxs are:
            => It.

         This class is derived from the yyy class. The abstraction it layers on top of yyy includes the following:
            => It.
      </PRE>
   </BLOCKQUOTE>

Subclass
   <BLOCKQUOTE>
      <PRE id="unindent">
         This class is derived from the yyy class. The abstraction it layers on top of yyy includes the
         following:
            => It.
      </PRE>
   </BLOCKQUOTE>

Usage
   <BLOCKQUOTE>
      <PRE id="unindent">
      </PRE>
   </BLOCKQUOTE>

<P>
   <DL>
      <DT>
         <B>
            Example usage:
         </B>
         <DD>
            <BLOCKQUOTE>
               <PRE id="unindent">
                  *java cosmicabyss.com.app.SourceCodeFileBasicFamily -t cpp
               </PRE>
            </BLOCKQUOTE>
         </DD>
      </DT>
      <DT>
         <B>
            View Source:
         </B>
         <DD>
            <A href="SourceCodeFileBasicFamily.java.html">
               SourceCodeFileBasicFamily.java
            </A>
         </DD>
      </DT>
      <DT>
         <B>
            Author:
         </B>
         <DD>
            <A href="mailto:sourcecode.v01@cosmicabyss.com">
               Allen Baker
            </A>
         </DD>
      </DT>
   </DL>
*//*
======================================================================================================================== */
public class SourceCodeFileBasicFamily extends SourceCodeFile
   {



   /*:.
   ==============================================================================================================
   @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@[  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(SourceCodeFileBasicFamily.class.getName());
   private static final int      DFLT_LINE_LEN = ConsoleMessage.defaultLineLength();



   /*:.
   ==============================================================================================================
   @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@[  Types  ]@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
   ============================================================================================================== */
   /*:.
   ==============================================================================================================
   <<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<[  Enums  ]>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>
   ============================================================================================================== */
   /*:.
   ==============================================================================================================
   <<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<[  Structs  ]>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>
   ============================================================================================================== */
   /*:.
   ==============================================================================================================
   <<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<[  Classes  ]>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>
   ============================================================================================================== */
   /*:.
   ==============================================================================================================
   <<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<[  Interfaces  ]>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>
   ============================================================================================================== */
   /*:.
   ==============================================================================================================
   @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@[  Variables  ]@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
   ============================================================================================================== */



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



   /*:.
   ==============================================================================================================
   @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@[  Functions  ]@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
   ============================================================================================================== */
   /*:.
   ==============================================================================================================
   <<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<[  Constructors  ]>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>
   ============================================================================================================== */



   /*:                                    
   ====================================================================================================
   [][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][]
   ==================================================================================================== *//**
   This method creates a SourceCodeFile class object.

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

   *//*
   ---------------------------------------------------------------------------------------------------- */
   public SourceCodeFileBasicFamily(XFile pXFile) throws Exception
      {
      super(pXFile.getCanonicalPath());
      initializeInstanceConstantsAndVariables();
      }



   /*:                                    
   ====================================================================================================
   [][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][]
   ==================================================================================================== *//**
   This method creates a SourceCodeFile class object.

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

   *//*
   ---------------------------------------------------------------------------------------------------- */
   public SourceCodeFileBasicFamily(TextFile pTextFile) throws Exception
      {
      super(pTextFile.getCanonicalPath());
      initializeInstanceConstantsAndVariables();
      }



   /*:                                    
   ====================================================================================================
   [][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][]
   ==================================================================================================== *//**
   This method creates a SourceCodeFile class object.

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

   *//*
   ---------------------------------------------------------------------------------------------------- */
   public SourceCodeFileBasicFamily(SourceCodeFile pSourceCodeFile) throws Exception
      {
      super(pSourceCodeFile.getCanonicalPath());
      initializeInstanceConstantsAndVariables();
      }



   /*:                                    
   ====================================================================================================
   [][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][]
   ==================================================================================================== *//**
   This method creates a SourceCodeFile class object.

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

   *//*
   ---------------------------------------------------------------------------------------------------- */
   public SourceCodeFileBasicFamily(URI pUri) throws Exception
      {
      super(pUri);
      initializeInstanceConstantsAndVariables();
      }



   /*:                                    
   ====================================================================================================
   [][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][]
   ==================================================================================================== *//**
   This method creates a SourceCodeFile class object.

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

   *//*
   ---------------------------------------------------------------------------------------------------- */
   public SourceCodeFileBasicFamily(File pFile) throws Exception
      {
      super(pFile.getCanonicalPath());
      initializeInstanceConstantsAndVariables();
      }



   /*:                                    
   ====================================================================================================
   [][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][]
   ==================================================================================================== *//**
   This method creates a SourceCodeFile class object.

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

   *//*
   ---------------------------------------------------------------------------------------------------- */
   public <Type> SourceCodeFileBasicFamily(File pParent, Type pChild) throws Exception
      {
      super(pParent,pChild);
      initializeInstanceConstantsAndVariables();
      }



   /*:                                    
   ====================================================================================================
   [][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][]
   ==================================================================================================== *//**
   This method creates a SourceCodeFile class object.

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

   *//*
   ---------------------------------------------------------------------------------------------------- */
   public <Type> SourceCodeFileBasicFamily(Type pPathname) throws Exception
      {
      super(pPathname);
      initializeInstanceConstantsAndVariables();
      }



   /*:                                    
   ====================================================================================================
   [][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][]
   ==================================================================================================== *//**
   This method creates a SourceCodeFile class object.

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

   *//*
   ---------------------------------------------------------------------------------------------------- */
   public <Type1,Type2> SourceCodeFileBasicFamily(Type1 pParent, Type2 pChild) throws Exception
      {
      super(pParent,pChild);
      initializeInstanceConstantsAndVariables();
      }



   /*:.
   ==============================================================================================================
   <<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<[  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();
      }



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

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

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



   /*:                                    
   ====================================================================================================
   [][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][]
   ==================================================================================================== *//**
   This method initializes all the instance constants and variables. The intent of this method is to
   encapsulate all the common instance initializations in one place that can be called from all the
   constructors.

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

   @return
      True if the initialization succeeded, flase otherwise.
   *//*
   ---------------------------------------------------------------------------------------------------- */
   private boolean initializeInstanceConstantsAndVariables() throws Exception
      {
      boolean  successCode = true;

      if (successCode)
         {
         ;
         }
      return successCode;
      }



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



   /*:                                    
   ====================================================================================================
   [][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][]
   ==================================================================================================== *//**
   This method wraps the textual content of all of this source code file's multi-line comments that are
   delimited by specified start comment (pStartDelimiter) and end comment delimiters (pEndDelimiter) so
   that they fit within a specified width (pFieldWidth).

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

   @param
      pStartDelimiter is the string that demarcates the beginning of a multi-line comment that is to be
      wrapped.
   @param
      pEndDelimiter is the string that demarcates the ending of a multi-line comment that is to be
      wrapped.
   @param
      pFieldWidth is the width to which the comments are to be wrapped.
   *//*
   ---------------------------------------------------------------------------------------------------- */
   private void wrapCommentText(XString pStartDelimiter, XString pEndDelimiter, int pFieldWidth) throws Exception
      {
      /*.
      ==========================================================================================
      This method makes no sense on directory files, this must be a normal file
      ------------------------------------------------------------------------------------------ */
      if (this.isDirectory()) return;
      /*.
      ==========================================================================================
       We'll output the modified version of the file to a temp file so if the process fails
       midway through, we don't corrupt the
      Original file
      ------------------------------------------------------------------------------------------ */
      XFile  iFile = new XFile(this.getCanonicalPath());
      XFile  oFile = new XFile(File.createTempFile("SourceCodeFileBasicFamily-",".tmp"));
      /*.
      ==========================================================================================
      Create the new file with the modifications
      ------------------------------------------------------------------------------------------ */
      wrapCommentText
         (
         iFile.getCanonicalPath(),
         oFile.getCanonicalPath(),
         pStartDelimiter,
         pEndDelimiter,
         pFieldWidth
         );
      /*.
      ==========================================================================================
      Delete the original file
      ------------------------------------------------------------------------------------------ */
      if ( ! iFile.delete())
         {
         throw new Exception("Cannot delete " + iFile.getCanonicalPath());
         }
      /*.
      ==========================================================================================
      And replace it with the new file.
      ------------------------------------------------------------------------------------------ */
      if ( ! oFile.renameTo(iFile))
         {
         throw new Exception("Cannot rename " + oFile.getCanonicalPath());
         }
      }



   /*:                                    
   ====================================================================================================
   [][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][]
   ==================================================================================================== *//**
   This method wraps the textual content of all of a source code file's (pFileName) multi-line comments
   that are delimited by specified start comment (pStartDelimiter) and end comment delimiters
   (pEndDelimiter) so that they fit within a specified width (pFieldWidth).

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

   @param
      pFileName is the name of the source code file to wrap all the multi-line comments in.
   @param
      pStartDelimiter is the string that demarcates the beginning of a multi-line comment that is to be
      wrapped.
   @param
      pEndDelimiter is the string that demarcates the ending of a multi-line comment that is to be
      wrapped.
   @param
      pFieldWidth is the width to which the comments are to be wrapped.
   *//*
   ---------------------------------------------------------------------------------------------------- */
   public static <Type1,Type2,Type3,Type4> void wrapCommentText
      (
      Type1  pFileIn,
      Type2  pFileOut,
      Type3  pStartDelimiter,
      Type4  pEndDelimiter,
      int    pFieldWidth
      )
      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);
      /*.
      ==========================================================================================
      Put the entire content of the input file into a StringBuffer
      ------------------------------------------------------------------------------------------ */
      StringBuffer  theWholeFile = new StringBuffer(2 * UMath.ONE_MEG);
      while (iter.hasNext())
         {
         XString  s = iter.next();
         s = s.trimRight();
         s = s.concat("\n");
         theWholeFile.append(s.toString());
         }
      /*.
      ==========================================================================================
      For each pStartDelimiter in the file...
      ------------------------------------------------------------------------------------------ */
      String   startDelimiter       = pStartDelimiter.toString();
      String   endDelimiter         = pEndDelimiter.toString();
      int      startDelimiterLength = startDelimiter.length();
      int      endDelimiterLength   = endDelimiter.length();
      int      startSearchFromIdx   = 0;
      int      startDelimiterIdx    = 0;
      XString  commentText          = null;
      while ((startDelimiterIdx = theWholeFile.indexOf(startDelimiter, startSearchFromIdx)) != (-1))
         {
         /*.
         ==========================================================================================
         Ignore sections of code that are commented out with single-line comments.
         ------------------------------------------------------------------------------------------ */
         if (lineIsCommentedOut(theWholeFile, startDelimiterIdx))
            {
            startSearchFromIdx = startDelimiterIdx + startDelimiterLength;
            }
         else
            {
            /*.
            ==========================================================================================
            StartCommentTextIdx is the index of the first char in the comment's text.
            EndCommentTextIdx is the index of the last char in the comment's text *plus 1*.
            ------------------------------------------------------------------------------------------ */
            int  startCommentTextIdx = startDelimiterIdx + startDelimiterLength;
            int  endCommentTextIdx   = 0;
            /*.
            ==========================================================================================
            Find the indent whitespace for this comment.
            ------------------------------------------------------------------------------------------ */
            XString indent         = new XString("");
            int     indentLength   = 0;
            String  thisLine       = UString.lineContainingIndex(theWholeFile, startDelimiterIdx);
            int     indentIdx      = 0;
            while (thisLine.charAt(indentIdx) == ' ')
               {
               indentIdx++;
               }
            indent       = new XString(thisLine.substring(0, indentIdx));
            indentLength = indent.length();
            /*.
            ==========================================================================================
            Find the end index of the startDelimiter's matching endDelimiter - it's the first
            uncommented out end delimiter found
            ------------------------------------------------------------------------------------------ */
            int  idxAfterEndDelimiter = (startDelimiterIdx + startDelimiterLength);
            while (true)
               {
               idxAfterEndDelimiter = (int)UString.indexAfterDelimitedSpan(theWholeFile, startDelimiter, endDelimiter, idxAfterEndDelimiter, true);
               if (idxAfterEndDelimiter == (-1)) break;
               if (! lineIsCommentedOut(theWholeFile, idxAfterEndDelimiter - endDelimiterLength)) break;
               }
            /*.
            ==========================================================================================
            It should never happen in a properly formed file, but if no matching end delimiter was
            located, don't do anything else.
            ------------------------------------------------------------------------------------------ */
            if (idxAfterEndDelimiter == (-1))
               {
               System.out.println(theWholeFile.substring( UMath.max(0,startDelimiterIdx-500), UMath.min(theWholeFile.length(),startDelimiterIdx+500) ));
               throw new Exception
                  (
                  "CommentFixer.wrapCommentText(): Malformed comments in file:\n"  +
                  "   idxAfterEndDelimiter is: -1\n"                               +
                  "   startDelimiterIdx is:    "    + startDelimiterIdx    +  "\n" +
                  "   startDelimiterLength is: "    + startDelimiterLength +  "\n" +
                  "   indent is:               <"   + indent               + ">\n" +
                  "   endDelimiterLength is:   "    + endDelimiterLength   +  "\n"
                  );
               }
            else
               {
               /*.
               ==========================================================================================
               The actual comment text ends on the line before the line containing the end delimiter.
               Doing this backup thing here for the end idx eliminates the problem of when a comment is
               itself commented out with a double slash. Without backing up to the newline preceeding the
               '//', the '//' would be considered part of the comment text.
               ------------------------------------------------------------------------------------------ */
               endCommentTextIdx = idxAfterEndDelimiter - endDelimiterLength - 1;
               while (theWholeFile.charAt(endCommentTextIdx) != '\n')
                  {
                  endCommentTextIdx--;
                  }
               endCommentTextIdx++;
               /*.
               ==========================================================================================
               Grab all the content between the start and end delimiters into a single XString for
               wrapping
               ------------------------------------------------------------------------------------------ */
               commentText = new XString(theWholeFile.substring(startCommentTextIdx, endCommentTextIdx));
               /*.
               ==========================================================================================
               Wrap it and put the entire wrapped content into a single XString
               ------------------------------------------------------------------------------------------ */
               XString  wrappedComment = new XString("");
               if (!commentText.isEmpty())
                  {
                  ArrayList<XString>  wrappedLines = commentText.wordWrap(pFieldWidth + indentLength, new UString.BasicEnglishCapitalizer());
                  commentText = new XString("");
                  for (XString wrappedLine : wrappedLines)
                     {
                     commentText = commentText.concat(wrappedLine + "\n");
                     }
                  }
               /*.
               ==========================================================================================
               Replace the original comment content with the wrapped content
               ------------------------------------------------------------------------------------------ */
               theWholeFile = theWholeFile.replace(startCommentTextIdx, endCommentTextIdx, commentText.toString());
               }
            /*.
            ==========================================================================================
            To continue searching for comments, increment the place in theWholeFile from which to
            start looking so it is past the comment we just processed
            ------------------------------------------------------------------------------------------ */
            startSearchFromIdx = startDelimiterIdx + startDelimiterLength + commentText.length() + indent.length() + endDelimiterLength;
            }
         }
      /*.
      ==========================================================================================
      Finish writing the output file, flush its buffers to physical storage, and close the it.
      ------------------------------------------------------------------------------------------ */
      output.println(theWholeFile.toString());
      output.flush();
      output.close();
      }



   /*:                                    
   ====================================================================================================
   [][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][]
   ==================================================================================================== *//**
   This method determines whether or not the line of text in a String (or any object convertable to a
   String) (pStr) containing the indexed (pIdx) character is commented out.

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

   @return
      This method returns true if the line of text in a String (or any object convertable to a String)
      (pStr) containing the indexed (pIdx) character is commented out. Otherwise, it returns false.

   @param
      pSringBuffer contains the line of text
   @param
      pIdx is the index that determines the line of text in pStr to check to see if it is commented
      out.
   *//*
   ---------------------------------------------------------------------------------------------------- */
   private static <Type> boolean lineIsCommentedOut(Type pStr, int pIdx)
      {
      /*.
      ==========================================================================================
      If pIdx is < 1, it is either an invalid negative number or there is no room for a start
      comment delimiter.
      ------------------------------------------------------------------------------------------ */
      if (pIdx < 1) return false;
      /*.
      ==========================================================================================
      Get the line containing pStr.charAt(pIdx)
      ------------------------------------------------------------------------------------------ */
      String  thisLine = UString.lineContainingIndex(pStr, pIdx);
      return thisLine.contains("//");
      }



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

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

   @return
      A reference to this object

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

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



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

   <P><B>Implementation: </B><A HREF="SourceCodeFileBasicFamily.java.html#015">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
      ------------------------------------------------------------------------------------------ */
      SourceCodeFileBasicFamily  obj = new SourceCodeFileBasicFamily("SourceCodeFileBasicFamily-Test.cType");
      /*.
      ==========================================================================================
      Test code
      ------------------------------------------------------------------------------------------ */
      obj.test();
      }



   }  // End of Class SourceCodeFileBasicFamily



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



   /*:                                    
   ====================================================================================================
   [][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][][]
   ==================================================================================================== *//**
   This method => -> -- c c c c c c c

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

   @return
      This method returns

   @exception
      Xx is thrown when
   @exception
      Yy is thrown when

   @param
      PX (optional)(input/output)(output) is the
   @param
      PY (optional)(input/output)(output) is the
   *//*
   ---------------------------------------------------------------------------------------------------- */
      /*.
      ==========================================================================================
      ------------------------------------------------------------------------------------------ */
   /*:.
   ==============================================================================================================
   @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@[  Section Level 0 Banner  ]@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
   ============================================================================================================== */
   /*:.
   ==============================================================================================================
   <<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<[  Section Level 1 Banner  ]>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>
   ============================================================================================================== */
   /*:.
   ==============================================================================================================
   :::::::::::::::::::::::::::::::::::::::::[  Section Level 2 Banner  ]:::::::::::::::::::::::::::::::::::::::::
   ============================================================================================================== */
   /*:.
   ==============================================================================================================
   -----------------------------------------[  Section Level 3 Banner  ]-----------------------------------------
   ============================================================================================================== */
   /*:.
   ==============================================================================================================
                                            [  Section Level 4 Banner  ]
   ============================================================================================================== */