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

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



/*::
======================================================================================================================== *//**
Instances of this class represent a source code file.

Salient characteristics of a SourceCodeFile are:
   <BLOCKQUOTE>
      => It contains programming language source code such as Basic, VBA, C, C++, C#, Java, etc..
   </BLOCKQUOTE>

Subclass
   <BLOCKQUOTE>
      This class is derived from the TextFile class. The abstraction it layers on top of TextFile includes the
      following:
         <BLOCKQUOTE>
            => It is a collection of computer instructions (including comments) written using some human-readable
               Computer Language as text.
            => It can be transformed by a compiler program into low-level machine code that is executable by a computer.
            => It is written in compliance with language-specific syntax rules as well as in compliance with
               Language-specific Code formatting conventions.
         </BLOCKQUOTE>
   </BLOCKQUOTE>

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

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



   /*:.
   ==============================================================================================================
   @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@[  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(SourceCodeFile.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();
   /*.
   ==========================================================================================
   iCanonicalPath:
      The fully qualified (canonical) pathname for the source code file represented by this
      instance.
         A PATHNAME is a string that identifies a SINGLE specific file or directory. A
         pATHNAME is CONCRETE, meaning it does not include any wildcards or other pattern
         characters that must be resolved.
            FULLY QUALIFIED PATHNAME: A FULLY QUALIFIED PATHNAME is a PATHNAME that includes
            the ROOT in the TREE component and contains all three components: DRIVE, TREE,
            and FILENAME
   iLanguage:
      The name of the programming language that this source code file is coded in.
   iLayoutVersion:
      A number indicating the version of the code layout formatting conventions that this
      source code file complies with. The default version is 0.
   ------------------------------------------------------------------------------------------ */
   protected String  iLanguage      = null;
   protected long    iLayoutVersion = 0;



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



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

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

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



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

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

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



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

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

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



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

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

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



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

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

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



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

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

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



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

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

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



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

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

   *//*
   ---------------------------------------------------------------------------------------------------- */
   public <Type1,Type2> SourceCodeFile(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="SourceCodeFile.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="SourceCodeFile.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 sets the ConsoleStream for this object.

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

   @return
      A reference to this object

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

   @return
      A reference to this object
   *//*
   ---------------------------------------------------------------------------------------------------- */
   public SourceCodeFile 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.SourceCodeFile
            </DD>
         </DT>
      </DL>

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



   }  // End of Class SourceCodeFile



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



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

   <P><B>Implementation: </B><A HREF="SourceCodeFile.java.html#013">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  ]
   ============================================================================================================== */