package Torello.JavaDoc;

import java.io.IOException;
import java.util.Vector;
import java.util.Iterator;
import java.util.function.Consumer;
import java.util.stream.Stream;

import Torello.Java.*;
import static Torello.Java.C.*;

import Torello.Java.Additional.Ret6;

import Torello.JDUInternal.Annotations.TypeAnnotations.Mirror.TypeAnnotationMirrors;
import Torello.JDUInternal.Parse.HTML.Signature.D1_CallableSignature;

import Torello.Java.ReadOnly.ReadOnlyList;
import Torello.Java.ReadOnly.ReadOnlyArrayList;

/**
 * Parent-class of {@link JavaDocHTMLFile} and the source-code parsing classes.
 * <EMBED CLASS='external-html' DATA-FILE-ID=PARSEDFILE>
 */
public abstract class ParsedFile implements java.io.Serializable
{
    /** <EMBED CLASS='external-html' DATA-FILE-ID=SVUID> */
    public static final long serialVersionUID = 1;

    private static final ReadOnlyList<String> EMPTY_RO_LIST = ReadOnlyList.of();


    // ********************************************************************************************
    // ********************************************************************************************
    // Constructor
    // ********************************************************************************************
    // ********************************************************************************************


    // This constructor is an "almost" zero-work constructor.  It merely accepts many parameters
    // and then initializes this class fields with those parameter values.
    // Subclasses should use this constructor to initialize these fields.
    //
    // The follopwing two classes inherit this class:
    //
    //  Torello.JavaDoc.JavaDocHTMLFile
    //  Torello.JDUInternal.Parse.Java.JSCF.JavaSourceCodeFile

    protected ParsedFile(
            final String fileName,

            final String                simpleNameWithContainersAndGenerics,
            final String                packageName,
            final CIET                  ciet,
            final ReadOnlyList<String>  genericParameters,
            final String                fullNameNoGenerics,
            final String                typeNameJOW,

            final int startLineNumber,
            final int endLineNumber,
            final int jdStartLineNumber,
            final int jdEndLineNumber,
            final int typeLineCount,
            final int typeSizeChars,

            final String javaSrcFileAsStr,

            final ReadOnlyList<Method>          methods,
            final ReadOnlyList<Field>           fields,
            final ReadOnlyList<Constructor>     constructors,
            final ReadOnlyList<EnumConstant>    enumConstants,
            final ReadOnlyList<AnnotationElem>  annotationElems,
            final ReadOnlyList<NestedType>      nestedTypes
        )
    {
        this.fileName                               = fileName;
        this.simpleNameWithContainersAndGenerics    = simpleNameWithContainersAndGenerics;
        this.packageName                            = packageName;
        this.ciet                                   = ciet;
        this.genericParameters                      = genericParameters;
        this.fullNameNoGenerics                     = fullNameNoGenerics;

        this.simpleNameWithPossibleContainers =
            simpleNameWithContainersAndGenerics.replaceFirst("<.*>", "");

        this.isInner =
            this.simpleNameWithPossibleContainers.indexOf(".") != -1;

        this.typeNameJOW    = typeNameJOW;
        this.isGeneric      = genericParameters.size() > 0;

        this.startLineNumber    = startLineNumber;
        this.endLineNumber      = endLineNumber;
        this.jdStartLineNumber  = jdStartLineNumber;
        this.jdEndLineNumber    = jdEndLineNumber;
        this.typeLineCount      = typeLineCount;
        this.typeSizeChars      = typeSizeChars;

        this.javaSrcFileAsStr   = javaSrcFileAsStr;

        this.methods            = methods;
        this.fields             = fields;
        this.constructors       = constructors;
        this.annotationElems    = annotationElems;
        this.enumConstants      = enumConstants;
        this.nestedTypes        = nestedTypes;

        // To get the container classes, just split on the period.
        String[] classes = this.simpleNameWithPossibleContainers.split(".");

        // This removes the very-last element resulting from the split.
        this.containerClasses = (classes.length > 1)
            ? new ReadOnlyArrayList<>(classes)
            : EMPTY_RO_LIST;
    }


    // ********************************************************************************************
    // ********************************************************************************************
    // Annotation-Mirror class
    // ********************************************************************************************
    // ********************************************************************************************


    // @StaticFunctional and @JDHeaderBackgroundImg - saves all the info from those Annotations
    // EXPORT_PORTAL method: Used by MainFilesProcessor.PART_TWO_Do_The_Rest
    // This is not a 'public' field, because the information it contains is **ONLY** the info that
    // was collected from those two annotations - NOT ALL ANNOTATIONS!
    //
    // That information is mostly totally useless to the end user.

    /**
     * Stores information provided by the JavaDoc Upgrader Annotations.  Note, this Annotation
     * Mirror does not contain information about any / all annotations used inside of Java Source
     * Code Files, but rather only the ones created by this API.
     *
     * <BR /><BR />These include <B STYLE='color: blue'>{@code @StaticFunctional}</B> and also
     * <B STYLE='color: blue'>{@code @JDHeaderBackgroundImg}</B>
     */
    protected TypeAnnotationMirrors typeAnnotationMirrors = null;


    // ********************************************************************************************
    // ********************************************************************************************
    // Main String-Data Stuff
    // ********************************************************************************************
    // ********************************************************************************************


    /**
     * This field simply contains the entire contents of the {@code '.java'} Source-Code File from
     * whence this {@code ParsedFile} instance originated.
     * 
     * <BR /><BR />Note that for in for the sub-class {@link JavaDocHTMLFile}, when the HTML file
     * which was parsed represents an inner-class / nested-type, this field will still contain the
     * entire contents of the top-level enclosing java type (as a {@code String}) in this field.
     * 
     * <BR /><BR />For instance, if a {@link JavaDocHTMLFile} (which inherits this class,
     * {@code ParsedFile}) instance had been generated for the Java-HTML inner-class
     * {@code Torello.HTML.Attributes.Filter}, which happens to be a nested type of class
     * {@code Torello.HTML.Attributes}, this field would contain the text-characters of the
     * Source-File {@code Torello/HTML/Attributes.java} in {@code String}-format (as character
     * data).
     */
    public final String javaSrcFileAsStr;

    /** Contains the file-name from which this instance was derived */
    public final String fileName;

    /**
     * Holds the name of a Class / CIET / Type.  A {@code 'ParsedFile'} represents a class,
     * interface, or enumerated-type.  This name stored in this field <B>IS NOT</B> the
     * fully-qualified (Package-Name information included) name.  The Java-Package in which this
     * Class or Type resides isn't incorporated into the name stored in this field.
     * 
     * <BR /><BR />This {@code String}-Field <B><I>will have any &amp; all Generic Type Parameters
     * appended to its name</I></B> - if this CIET represents a generic with such Type-Parameters.
     * 
     * <BR /><BR />If this {@code CIET}/Type represents a Nested-Class / Inner-Type, <I>the names 
     * of the containing {@code CIET} / Types are included</I> in this {@code String}-Field.
     * 
     * <BR /><BR /><TABLE CLASS=JDBriefTable>
     * <TR>
     *      <TH>Output Value</TH>
     *      <TH>Input {@code CIET} / Type</TH>
     *      </TR>
     * <TR>
     *      <TD>{@code "Integer"}</TD>
     *      <TD>interface {@code java.lang.Integer}</TD>
     *      </TR>
     * <TR>
     *      <TD>{@code "Vector<E>"}</TD>
     *      <TD>class {@code java.util.Vector<E>}</TD>
     *      </TR>
     * <TR>
     *      <TD>{@code "Base.Decoder"}</TD>
     *      <TD>class {@code java.util.Base64.Decoder}</TD>
     *      </TR>
     * <TR>
     *      <TD>{@code "Map.Entry<K, V>"}</TD>
     *      <TD>interface {@code java.util.Map.Entry<K, V>}</TD>
     *      </TR>
     * </TABLE>
     */
    public final String simpleNameWithContainersAndGenerics;

    /**
     * This {@code String}-Field holds the <I>fully qualified {@code CIET} name</I> - which simply
     * means that any Java-Package information that is available shall be included in the name that
     * is stored in this field.  By implication, if the Package-Name is stored, then this
     * {@code String}-Field must also hold any Container-Class names for this CIET/Type - in cases 
     * where this type is, indeed, a nested or inner type.
     * 
     * <BR /><BR />If this {@code CIET}-Type happens to be a Java Generic with Generic Type
     * Parameters (the {@code 'E'} in type {@code java.util.Vector<E>}, this information <B>WILL
     * NOT</B> include that text stored within this {@code String}-Field. 
     * 
     * <BR /><TABLE CLASS=JDBriefTable>
     * <TR>
     *      <TH>Output Value</TH>
     *      <TH>Input {@code CIET} / Type</TH>
     *      </TR>
     * <TR>
     *      <TD>{@code "java.lang.Integer"}</TD>
     *      <TD>interface {@code java.lang.Integer}</TD>
     *      </TR>
     * <TR>
     *      <TD>{@code "java.util.Vector"}</TD>
     *      <TD>class {@code java.util.Vector<E>}</TD>
     *      </TR>
     * <TR>
     *      <TD>{@code "java.util.Base64.Decoder"}</TD>
     *      <TD>class {@code java.util.Base64.Decoder}</TD>
     *      </TR>
     * <TR>
     *      <TD>{@code "java.util.Map.Entry"}</TD>
     *      <TD>interface {@code java.util.Map.Entry<K, V>}</TD>
     *      </TR>
     * </TABLE>
     */
    public final String fullNameNoGenerics;

    /**
     * This the same as the {@link #simpleNameWithContainersAndGenerics} field, but leaves off
     * the Generic Type-Parameter {@code String's}.  If this class is representing a {@code CIET}
     * Type that happens to be a Nested-Type / Inner-Class, then the containing {@code CIET}
     * name(s) <B>ARE</B> included in this {@code String}-Field.
     * 
     * <BR /><TABLE CLASS=JDBriefTable>
     * <TR>
     *      <TH>Output Value</TH>
     *      <TH>Input {@code CIET} / Type</TH>
     *      </TR>
     * <TR>
     *      <TD>{@code "Integer"}</TD>
     *      <TD>interface {@code java.lang.Integer}</TD>
     *      </TR>
     * <TR>
     *      <TD>{@code "Vector"}</TD>
     *      <TD>class {@code java.util.Vector<E>}</TD>
     *      </TR>
     * <TR>
     *      <TD>{@code "Base64.Decoder"}</TD>
     *      <TD>class {@code java.util.Base64.Decoder}</TD>
     *      </TR>
     * <TR>
     *      <TD>{@code "Map.Entry"}</TD>
     *      <TD>interface {@code java.util.Map.Entry<K, V>}</TD>
     *      </TR>
     * </TABLE>
     */
    public final String simpleNameWithPossibleContainers;

    /**
     * <B CLASS=JDDescLabel>JOW: Just One Word</B>
     * 
     * <BR />The Java-Doc Upgrader utilizes a few naming conventions, one of which is that any 
     * time the acronym {@code 'JOW'} is used, it is intending to provide a name to a Java-Type.
     * Since there isn't an exact consensus on what information should be included in a Type-Name,
     * the {@code 'JOW'} Acronym simply implies that the <B STYLE='color: red;'><I>simplest name 
     * possible</I></B> (a single word name) is being stored in this field.
     * 
     * <BR /><BR />If this name is representing a {@code CIET}-Type that happens to be a
     * Java-Generic, and having Generic-Type Parameters, such {@code String}-Text <B>WILL NOT</B>
     * be included in this {@code String}-Field.
     * 
     * <BR /><BR />If this name is representing a {@code CIET}-Type that happens to be a
     * Nested-Type / Inner-Class, then the containing {@code CIET} name(s)
     * <B>ARE NOT</B> included in this {@code String}-Field.
     * 
     * <BR /><BR />Package-Name information will also not be stored in this field.
     * 
     * <BR /><TABLE CLASS=JDBriefTable>
     * <TR>
     *      <TH>Output Value</TH>
     *      <TH>Input {@code CIET} / Type</TH>
     *      </TR>
     * <TR>
     *      <TD>{@code "Integer"}</TD>
     *      <TD>interface {@code java.lang.Integer}</TD>
     *      </TR>
     * <TR>
     *      <TD>{@code "Vector"}</TD>
     *      <TD>class {@code java.util.Vector<E>}</TD>
     *      </TR>
     * <TR>
     *      <TD>{@code "Decoder"}</TD>
     *      <TD>class {@code java.util.Base64.Decoder}</TD>
     *      </TR>
     * <TR>
     *      <TD>{@code "Entry"}</TD>
     *      <TD>interface {@code java.util.Map.Entry<K, V>}</TD>
     *      </TR>
     * </TABLE>
     */
    public final String typeNameJOW;

    /**
     * Holds the package-name.  If this {@code ParsedFile} were for class {@code java.lang.String}
     * the {@code 'packageName'} would be {@code 'java.lang'}.
     */
    public final String packageName;


    // ********************************************************************************************
    // ********************************************************************************************
    // The Additional Stuff
    // ********************************************************************************************
    // ********************************************************************************************


    /**
     * The acronym 'CIET' simply means "Class, Interface or Enumerated-Type.  This public field
     * identifies whether this {@code ParsedFile} is for a class, an interface or an enumerated-type.
     */
    public final CIET ciet;

    /**
     * This identifies inner classes and interfaces.
     * 
     * <BR /><TABLE CLASS=JDBriefTable>
     * <TR> <TH>{@code 'isInner'} Field Value</TH>
     *      <TH>Input {@code CIET}</TH>
     *      </TR>
     * <TR> <TD>{@code false}</TD>
     *      <TD>interface {@code java.lang.Integer}</TD>
     *      </TR>
     * <TR> <TD>{@code false}</TD>
     *      <TD>class {@code java.util.Vector<E>}</TD>
     *      </TR>
     * <TR> <TD>{@code true}</TD>
     *      <TD>class {@code java.util.Base64.Decoder}</TD>
     *      </TR>
     * <TR> <TD>{@code true}</TD>
     *      <TD>interface {@code java.util.Map.Entry<K, V>}</TD>
     *      </TR>
     * </TABLE>
     */
    public final boolean isInner;

    /**
     * This identifies inner classes and interfaces.  For any class that is not an inner class,
     * this will be a zero-length {@code String[]} array.
     * 
     * <BR /><TABLE CLASS=JDBriefTable>
     * <TR> <TH>{@code 'containerClasses'} Value</TH>
     *      <TH>Input {@code CIET}</TH>
     *      </TR>
     * <TR> <TD><CODE>&lt;EMPTY-LIST&gt;</CODE></TD>
     *      <TD>interface {@code java.lang.Integer}</TD>
     *      </TR>
     * <TR> <TD><CODE>&lt;EMPTY-LIST&gt;</CODE></TD>
     *      <TD>class {@code java.util.Vector<E>}</TD>
     *      </TR>
     * <TR> <TD><CODE></CODE>&lcub; "Base64" &rcub;</TD>
     *      <TD>class {@code java.util.Base64.Decoder}</TD>
     *      </TR>
     * <TR> <TD><CODE></CODE>&lcub; "Map" &rcub;</TD>
     *      <TD>interface {@code java.util.Map.Entry<K, V>}</TD>
     *      </TR>
     * </TABLE>
     */
    public final ReadOnlyList<String> containerClasses;


    /**
     * This field will be {@code TRUE} anytime the {@link #genericParameters} field has
     * any elements.
     */
    public final boolean isGeneric;

    /**
     * If this represents a Java <B>Generic Class or Interface</B>, with generic type information,
     * the generic type parameters shall be saved here.
     */
    public final ReadOnlyList<String> genericParameters;


    /**
     * The line-number in the source-code file where this class definition actually begins.
     * 
     * <BR /><BR />Note that if this instance of {@code ParsedFile} is representing a Nessted-Type
     * / Inner-Class, then this field will contain the line-number where that inner-type's
     * definition begins inside the Enclosing-Class' {@code '.java'} file.
     */
    public final int startLineNumber;

    /**
     * The line-number in the source-code file where this class definition ends.  Often this will
     * just be the line-number of the last line in the {@code '.java'} file.
     * 
     * <BR /><BR />If this is a Nested-Type, this field will contain the line-number where the
     * definition of the Nested-type ends.
     */
    public final int endLineNumber;

    /**
     * The starting line-number of the JavaDoc Comment at the top of the class.  If this class
     * does not have a Java-Doc Comment, this field will contain {@code -1}.
     */
    public final int jdStartLineNumber;

    /**
     * The endiing line-number of the JavaDoc Comment at the top of the class.  If this class does
     * not have a Java-Doc Comment, this field will contain {@code -1}.
     */
    public final int jdEndLineNumber;

    /**
     * The number of lines of Source-Code inside this {@code '.java'} File.  If this instance of
     * {@code ParsedFile} represents an Inner-Type (Nested-Class), then this field will contain 
     * a value that corresponds only to the number of lines used by the Nested-Type within the
     * context of the entire Enclosing-Class {@code '.java'} file.
     */
    public final int typeLineCount;

    /**
     * The number of characters / bytes of Source-Code inside this {@code '.java'} File.  If this
     * instance of {@code ParsedFile} represents an Inner-Type (Nested-Class), then this field will
     * contain a value that corresponds only to the number of characters / bytes used by the
     * Nested-Type within the context of the entire Enclosing-Class {@code '.java'} file.
     */
    public final int typeSizeChars;


    // ********************************************************************************************
    // ********************************************************************************************
    // Members
    // ********************************************************************************************
    // ********************************************************************************************


    /**
     * This is the list of {@link Method} instances identified by the parser for this
     * {@code ParsedFile}
     */
    public final ReadOnlyList<Method> methods;

    /**
     * This is the list of {@link Constructor} instances identified by the parser for this
     * {@code ParsedFile}
     */
    public final ReadOnlyList<Constructor> constructors;


    /**
     * This is the list of {@link Field} instances identified by the parser for this
     * {@code ParsedFile}
     */
    public final ReadOnlyList<Field> fields;

    /**
     * This is the list of {@link AnnotationElem} instances identified by the parser for this
     * {@code ParsedFile}
     * <EMBED CLASS=defs DATA-DECL=AnnotationElem DATA-VEC=annotationElems DATA-KIND=annotation>
     * <EMBED CLASS='external-html' DATA-FILE-ID=PF_NOT_POSSIBLE>
     */
    public final ReadOnlyList<AnnotationElem> annotationElems;

    /**
     * This is the list of {@link EnumConstant} instances identified by the parser for this
     * {@code ParsedFile}
     * <EMBED CLASS=defs DATA-DECL=EnumConstant DATA-VEC=enumConstants DATA-KIND=enum>
     * <EMBED CLASS='external-html' DATA-FILE-ID=PF_NOT_POSSIBLE>
     * @see #enumConstants
     */
    public final ReadOnlyList<EnumConstant> enumConstants;

    /**
     * This is the list of {@link NestedType} instances identified by the parser for this
     * {@code ParsedFile}
     */
    public final ReadOnlyList<NestedType> nestedTypes;


    // ********************************************************************************************
    // ********************************************************************************************
    // FIND.
    // ********************************************************************************************
    // ********************************************************************************************


    /**
     * Finds a Method having the characteristics specified by parameter {@code 'cSig'}.
     * 
     * @param cSig An internally generated representation of a Java-Method extrapolated from the
     * information available on a Java-Doc HTML Detail Section
     * 
     * @return A method that matches the requested Method-Signature
     */
    public Method findMethod(D1_CallableSignature cSig)
    {
        for (Method method : methods)

            if (    method.name.equals(cSig.name)
                &&  method.returnTypeJOW.equals(cSig.returnTypeJOW)
                &&  method.nearlyEqualsCallableSig(cSig)
            )
                return method;

        return null;
    }

    /**
     * Finds a Constructor having the characteristics specified by parameter {@code 'cSig'}.
     * 
     * @param cSig An internally generated representation of a Java-Constructor extrapolated from
     * the information available on a Java-Doc HTML Detail Section
     * 
     * @return A Constructor that matches the requested Constructor-Signature
     */
    public Constructor findConstructor(D1_CallableSignature cSig)
    {
        for (Constructor ctor : constructors) if (ctor.nearlyEqualsCallableSig(cSig)) return ctor;
        return null;
    }

    /**
     * Returns all internally-stored {@code Method} instances whose {@code Method#name} field
     * matches {@code 'name'}
     * 
     * @param methodName The name of the {@code Method}
     * 
     * @return An instance of {@code Stream<Method>}of all {@code Method's} named {@code 'name'}
     * 
     * @see #methods
     * @see Method#name
     */
    public Stream<Method> findMethods(String methodName)
    {
        Stream.Builder<Method> b = Stream.builder();
        for (Method method : methods) if (method.name.equals(methodName)) b.accept(method);
        return b.build();
    }

    /**
     * Returns all internally-stored {@code Constructor} instances for instances whose accepted
     * parameters-list has a length equal to {@code numParameters}.
     * 
     * @param numParameters The number of parameters accepted by the {@code Constructor} being
     * searched.
     * 
     * @return An instance of {@code Stream<Constructor>} containing all {@code Constructor's}
     * whose number of parameterss equals {@code 'numParameters'}
     * 
     * @see #constructors
     * @see Constructor#numParameters()
     */
    public Stream<Constructor> findConstructors(int numParameters)
    {
        Stream.Builder<Constructor> b = Stream.builder();

        for (Constructor constructor : constructors)
            if (constructor.numParameters() == numParameters)
                b.accept(constructor);

        return b.build();
    }

    /**
     * <EMBED CLASS=defs DATA-DECL=Field>
     * <EMBED CLASS='external-html' DATA-FILE-ID=PF_FIND_N_DESC>
     * @param name The name of the {@code Field}
     * @return <EMBED CLASS='external-html' DATA-FILE-ID=PF_FIND_N_RET>
     * @see Declaration#name
     * @see #fields
     */
    public Field findField(String name)
    {
        for (Field field : fields) if (field.name.equals(name)) return field;
        return null;
    }

    /**
     * <EMBED CLASS=defs DATA-DECL=AnnotationElem DATA-KIND=annotation>
     * <EMBED CLASS='external-html' DATA-FILE-ID=PF_FIND_N_DESC>
     * <EMBED CLASS='external-html' DATA-FILE-ID=PF_NOT_POSSIBLE>
     * @param name The name of the {@code AnnotationElem}
     * @return <EMBED CLASS='external-html' DATA-FILE-ID=PF_FIND_N_RET>
     * @see Declaration#name
     * @see #annotationElems
     */
    public AnnotationElem findAnnotationElem(String name)
    {
        for (AnnotationElem ae : annotationElems) if (ae.name.equals(name)) return ae;
        return null;
    }

    /**
     * <EMBED CLASS=defs DATA-DECL=EnumConstant DATA-KIND=enum>
     * <EMBED CLASS='external-html' DATA-FILE-ID=PF_FIND_N_DESC>
     * <EMBED CLASS='external-html' DATA-FILE-ID=PF_NOT_POSSIBLE>
     * @param name The name of the {@code EnumConstant}
     * @return <EMBED CLASS='external-html' DATA-FILE-ID=PF_FIND_N_RET>
     * @see Declaration#name
     * @see #enumConstants
     */
    public EnumConstant findEnumConstant(String name)
    {
        for (EnumConstant ec : enumConstants) if (ec.name.equals(name)) return ec;
        return null;
    }

    /**
     * <EMBED CLASS=defs DATA-DECL=NestedType>
     * <EMBED CLASS='external-html' DATA-FILE-ID=PF_FIND_N_DESC>
     * @param name The name of the {@code NestedType}
     * @return <EMBED CLASS='external-html' DATA-FILE-ID=PF_FIND_N_RET>
     * @see Declaration#name
     * @see #nestedTypes
     */
    public NestedType findNestedType(String name)
    {
        for (NestedType nt : nestedTypes) if (nt.name.equals(name)) return nt;
        return null;
    }


    // ********************************************************************************************
    // ********************************************************************************************
    // toString()
    // ********************************************************************************************
    // ********************************************************************************************


    /**
     * Turns a {@code ParsedFile} result object, {@code 'this'}, into a {@code String}.  Passes
     * {@code '0'} to the standard flags-print method.
     */
    public String toString() { return toString(0); }

    /**
     * Turns a {@code ParsedFile} result object, {@code 'this'}, into a {@code java.lang.String}.
     * 
     * <BR /><BR />This will check for the {@code 'UNIX_COLORS'} flag in {@code class PF}.  If this
     * flag is  identified, then a few unix color codes are added to the output.
     * 
     * <BR /><BR /><B><SPAN STYLE="color: red;">IMPORTANT NOTE:</B></SPAN> The value of this flag
     * will be propagated to the individual {@code toString(int flag)} methods in each of the 
     * {@code Method, Field, Constructor} etc... - {@code toString(flag)} methods.
     * 
     * @return This returns a {@code String} that obeys the flag-requests by parameter flag.
     * @see Method#toString(int)
     * @see Constructor#toString(int)
     * @see Field#toString(int)
     */
    public String toString(int flags)
    {
        StringBuilder   sb  = new StringBuilder();
        boolean         c   = (flags & PF.UNIX_COLORS) > 0;

        StringBuilder typeParamsSB = new StringBuilder();
        for (String p : genericParameters) typeParamsSB.append(p + ", ");

        String typeParamsStr = (typeParamsSB.length() > 0)
            ? typeParamsSB.subSequence(0, typeParamsSB.length() - 1).toString()
            : "-";

        StringBuilder containerClassesSB = new StringBuilder();
        for (String p : containerClasses) containerClassesSB.append(p + ", ");

        String containerClassesStr = (containerClassesSB.length() > 0)
            ? containerClassesSB.subSequence(0, containerClassesSB.length() - 1).toString()
            : "-";
    
        sb.append(
            "******************************************************************\n" +
            "Fields in this 'ParsedFile' instance:\n"                              +
            "******************************************************************\n" +
            "fileName:                             " + fileName + '\n' +
            "simpleNameWithContainersAndGenerics:  " + simpleNameWithContainersAndGenerics + '\n' +
            "CIET:                                 " + ciet + '\n' +
            "packageName:                          " + packageName + '\n' +
            "simpleNameWithPossibleContainers:     " + simpleNameWithPossibleContainers + '\n' +
            "fullNameNoGenerics:                   " + fullNameNoGenerics + '\n' +
            "isGeneric:                            " + isGeneric + '\n' +
            "Type Parameters:                      " + typeParamsStr + '\n' +
            "isInner:                              " + isInner + '\n' +
            "Container Classes:                    " + containerClassesStr + "\n" +
            "\n" +
            "fields.size():                        " + fields.size() + '\n' +
            "methods.size():                       " + methods.size() + '\n' +
            "constructors.size():                  " + constructors.size() + '\n' +
            "annotationElems.size():               " + annotationElems.size() + '\n' +
            "enumConstants.size():                 " + enumConstants.size() + '\n' +
            "nestedTypes.size():                   " + nestedTypes.size() + "\n\n"
        );

        if (methods.size() > 0)
        {
            sb.append(  "******************************************************************\n" + 
                        (c ? BRED : "") + "Methods:\n" + (c ? RESET : "") +
                        "******************************************************************\n"  );

            for (Method m : methods) sb.append(m.toString(flags) + "\n\n");
        }

        if (constructors.size() > 0)
        {
            sb.append(  "******************************************************************\n" + 
                        (c ? BRED : "") + "Constructors:\n" + (c ? RESET : "") +
                        "******************************************************************\n"  );

            for (Constructor cs : constructors)  sb.append(cs.toString(flags) + "\n\n");
        }

        if (fields.size() > 0)
        {
            sb.append(  "******************************************************************\n" + 
                        (c ? BRED : "") + "Fields:\n" + (c ? RESET : "") +
                        "******************************************************************\n"  );

            for (Field f : fields) sb.append(f.toString(flags) + "\n\n");
        }

        if (annotationElems.size() > 0)
        {
            sb.append(  "******************************************************************\n" + 
                        (c ? BRED : "") + "Annotation-Elements:\n" + (c ? RESET : "") +
                        "******************************************************************\n"  );

            for (AnnotationElem ae : annotationElems) sb.append(ae.toString(flags) + "\n\n");
        }

        if (enumConstants.size() > 0)
        {
            sb.append(  "******************************************************************\n" + 
                        (c ? BRED : "") + "Enumerated Constants:\n" + (c ? RESET : "") +
                        "******************************************************************\n"  );

            for (EnumConstant ec : enumConstants) sb.append(ec.toString(flags) + "\n\n");
        }

        if (nestedTypes.size() > 0)
        {
            sb.append(  "******************************************************************\n" + 
                        (c ? BRED : "") + "Nested Types:\n" + (c ? RESET : "") +
                        "******************************************************************\n"  );

            for (NestedType nt : nestedTypes) sb.append(nt.toString(flags) + "\n\n");
        }

        return sb.toString();
    }

    /**
     * Provides a Quick Summary for this file.
     * 
     * @return The summary as a {@code java.lang.String}.  Nothing is actually printed by this
     * method.
     */
    public String quickSummary()
    {
        String typeParams = (genericParameters.size() == 0)
            ? ""
            : ("Generic Type-Parameters: " + 
                StrCSV.toCSV(this.genericParameters, true, true, null) + '\n');

        String ae = (annotationElems.size() == 0)
            ? ""
            : (", [" + BBLUE + StringParse.zeroPad(annotationElems.size()) + RESET +
                "] Annotation-Elements");

        String ec = (enumConstants.size() == 0)
            ? ""
            : (", [" + BBLUE + StringParse.zeroPad(enumConstants.size()) + RESET +
                "] Enum-Constants");

        String nt = (nestedTypes.size() == 0)
            ? ""
            : (", [" + BBLUE + StringParse.zeroPad(nestedTypes.size()) + RESET +
                "] Nested-Types");
    
        return
            "Name w/ Containers & Generics [" + BYELLOW + simpleNameWithContainersAndGenerics + RESET + "]\n" + 
            "Name w/ Any Containers        [" + BYELLOW + simpleNameWithPossibleContainers + RESET + "]\n" +
            "Name w/ Package-Info          [" + BYELLOW + fullNameNoGenerics + RESET + "]\n" +
            "Package [" + BYELLOW + packageName + RESET + "]\n" +
            "CIET    [" + BYELLOW + ciet        + RESET + "]\n" +
            typeParams +
            '[' + BBLUE + StringParse.zeroPad(fields.size())          + RESET + "] Fields, " +
            '[' + BBLUE + StringParse.zeroPad(constructors.size())    + RESET + "] Constructors, " +
            '[' + BBLUE + StringParse.zeroPad(methods.size())         + RESET + "] Methods" +
            ae + ec + nt + '\n';
    }

    /**
     * Provides a Vertical-List Abbreviated Summary for this file.
     * 
     * @param lineWidth The number of characters wide the member-summary lines should be.
     * @return The summary as a {@code java.lang.String}.  Nothing is actually printed by this
     * method.
     */
    public String abbreviatedSummary(int lineWidth)
    {
        String typeParams = (genericParameters.size() == 0)
            ? ""
            : ("Generic Type-Parameters: " + 
                StrCSV.toCSV(this.genericParameters, true, true, null) + '\n');

        String m = (methods.size() == 0)
            ? "Methods: *NONE*\n"
            : ("Methods:" + StrPrint.printListAbbrev
                (methods, lineWidth, 4, false, true, true) + '\n');

        String f = (fields.size() == 0)
            ? "Fields: *NONE*\n"
            : ("Fields:" + StrPrint.printListAbbrev
                (fields, lineWidth, 4, false, true, true) + '\n');

        String c = (constructors.size() == 0)
            ? "Constructors: *NONE*\n"
            : ("Constructors:" + StrPrint.printListAbbrev
                (constructors, lineWidth, 4, false, true, true) + '\n');
    
        String ec = (enumConstants.size() == 0)
            ? ""
            : ("Enum-Constants:" + StrPrint.printListAbbrev
                (enumConstants, lineWidth, 4, false, true, true) + '\n');
    
        String ae = (annotationElems.size() == 0)
            ? ""
            : ("Annotation-Elements:" + StrPrint.printListAbbrev
                (annotationElems, lineWidth, 4, false, true, true) + '\n');

        String nt = (nestedTypes.size() == 0)
            ? ""
            : ('[' + BBLUE + StringParse.zeroPad(nestedTypes.size()) + RESET +
                "] Nested-Types");
    
        return
            "Name w/ Containers & Generics " +
                '[' + BYELLOW + simpleNameWithContainersAndGenerics + RESET + "]\n" +

            "Name w/ Any Containers        " +
                '[' + BYELLOW + simpleNameWithPossibleContainers + RESET + "]\n" +

            "Package-Name Qualified        " +
                '[' + BYELLOW + fullNameNoGenerics + RESET + "]\n" +

            "Package [" + BYELLOW + packageName           + RESET + "]\n" +
            "CIET    [" + BYELLOW + ciet                  + RESET + "]\n" +

            typeParams +
            m + f + c + ec + ae + nt + '\n';
    }
}