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.DATA_RECORDS.MainLoopData.AnnotationsMirror;
import Torello.JDUInternal.DATA_RECORDS.MainLoopData.CallableSignature;

import Torello.Java.ReadOnly.ReadOnlyList;

/**
 * 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;


    // ********************************************************************************************
    // ********************************************************************************************
    // 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 AnnotationsMirror annotationsMirror = 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.  A {@code 'ParsedFile'} represents a class, interface, or enumerated-type.
     * This name is <B>NOT</B> the fully-qualified (package-included) name, and it <B><I>will
     * have any Generic Type Parameters appended</I></B>, if this CIET represents a generic that
     * has type-parameters.
     * 
     * <BR /><BR />If this {@code CIET} is an inner-class, <I>the containing {@code CIET} name
     * is included</I> in this {@code String} field.
     * 
     * <BR /><BR /><B>For Instance:</B>
     * 
     * <BR /><BR /><TABLE CLASS=JDBriefTable>
     * <TR> <TH>Input {@code CIET}</TH>
     *      <TH>{@code 'name'} Field Value</TH></TR>
     * <TR> <TD>interface {@code java.lang.Integer}</TD>
     *      <TD>{@code "Integer"}</TD></TR>
     * <TR> <TD>class {@code java.util.Vector<E>}</TD>
     *      <TD>{@code "Vector<E>"}</TD></TR>
     * <TR> <TD>class {@code java.util.Base64.Decoder}</TD>
     *      <TD>{@code "Base.Decoder"}</TD></TR>
     * <TR> <TD>interface {@code java.util.Map.Entry<K, V>}</TD>
     *      <TD>{@code "Map.Entry<K, V>"}</TD></TR>
     * </TABLE>
     * 
     * @see #simpleName
     * @see #fullyQualifiedName
     */
    public final String name;

    /**
     * This holds the <I>fully qualified {@code CIET} name</I> - which means that package and
     * containing class information is included.  If thi {@code CIET} is a Java Generic that 
     * happens to have Generic Type Parameters (the {@code 'E'} in {@code Vector<E>}, this name
     * <B>WILL NOT</B> include that text. 
     * 
     * <BR /><BR /><B>For Instance:</B>
     * 
     * <BR /><TABLE CLASS=JDBriefTable>
     * <TR><TH>Input {@code CIET}</TH>
     *      <TH>{@code 'fullyQualifiedName'} Field Value</TH></TR>
     * <TR> <TD>interface {@code java.lang.Integer}</TD>
     *      <TD>{@code "java.lang.Integer"}</TD></TR>
     * <TR> <TD>class {@code java.util.Vector<E>}</TD>
     *      <TD>{@code "java.util.Vector"}</TD></TR>
     * <TR> <TD>class {@code java.util.Base64.Decoder}</TD>
     *      <TD>{@code "java.util.Base64.Decoder"}</TD></TR>
     * <TR> <TD>interface {@code java.util.Map.Entry<K, V>}</TD>
     *      <TD>{@code "java.util.Map.Entry"}</TD></TR>
     * </TABLE>
     * 
     * @see #simpleName
     * @see #name
     */
    public final String fullyQualifiedName;

    /**
     * This the same as the {@link #name} parameter, but leaves off both the type-parameters, and
     * the fully-qualified package-name {@code String's}.  If this {@code CIET} is an inner class
     * the containing {@code CIET} name is included in this {@code String} field.
     * See the table below, for details:
     * 
     * <BR /><TABLE CLASS=JDBriefTable>
     * <TR><TH>Input {@code CIET}</TH><TH>{@code 'simpleName'} Field Value</TH></TR>
     * <TR><TD>interface {@code java.lang.Integer}</TD><TD>{@code "Integer"}</TD></TR>
     * <TR><TD>class {@code java.util.Vector<E>}</TD><TD>{@code "Vector"}</TD></TR>
     * <TR><TD>class {@code java.util.Base64.Decoder}</TD><TD>{@code "Base64.Decoder"}</TD></TR>
     * <TR><TD>interface {@code java.util.Map.Entry<K, V>}</TD><TD>{@code "Map.Entry"}</TD></TR>
     * </TABLE>
     * 
     * @see #name
     * @see #fullyQualifiedName
     */
    public final String simpleName;

    /**
     * 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></CODE>&lcub; &rcub;</TD>
     *      <TD>interface {@code java.lang.Integer}</TD>
     *      </TR>
     * <TR> <TD><CODE></CODE>&lcub; &rcub;</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>
     * 
     * @see #getContainerClasses()
     */
    protected final String[] containerClasses;

    /**
     * Returns the container classes (if any) for this class, interface, etc.
     * 
     * @return The list of container classes, from outer to inner, for this class.  If
     * this is a normal class that is not an <B>inner class</B>, this will return an empty
     * (zero-lengh) {@code String[]} array.
     * 
     * @see #containerClasses
     */
    public String[] getContainerClasses()
    {
        return (containerClasses.length > 0)
            ? containerClasses.clone()
            : StringParse.EMPTY_STR_ARRAY;
    }

    /**
     * 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.
     * 
     * @see #getGenericParameters()
     */
    protected final ReadOnlyList<String> genericParameters;

    /**
     * Returns the generic type parameters (if any) for this class or interface
     * 
     * @return The generic type parameters as a {@code String[]} array.  If this class is not a
     * <B>Java Generic</B>, a zero-length {@code String[]} array will be returned.
     * 
     * @see #genericParameters
     */
    public String[] getGenericParameters()
    { return genericParameters.toArray(new String[genericParameters.size()]); }

    /**
     * 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;


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


    /**
     * Subclasses of {@code 'ParsedFile'} should use this constructor to initialize these fields.
     *
     * <BR /><BR />Used by both {@link JavaDocHTMLFile} and {@code JavaSourceCodeFile}
     */
    protected ParsedFile(
            String                  fileName,
            String                  name,
            String                  packageName,
            CIET                    ciet,
            ReadOnlyList<String>    genericParameters,
            String                  fullyQualifiedName,
            int                     startLineNumber,
            int                     endLineNumber,
            int                     jdStartLineNumber,
            int                     jdEndLineNumber,
            int                     typeLineCount,
            int                     typeSizeChars,
            String                  javaSrcFileAsStr
        )
    {
        this.fileName           = fileName;
        this.name               = name;
        this.packageName        = packageName;
        this.ciet               = ciet;
        this.genericParameters  = genericParameters;
        this.fullyQualifiedName = fullyQualifiedName;
        this.simpleName         = this.name.replaceFirst("<.*>", "");
        this.isInner            = this.simpleName.indexOf(".") != -1;
        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;

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

        // This removes the very-last element resulting from the split.
        this.containerClasses = (classes.length > 1)
            ? java.util.Arrays.copyOf(classes, classes.length - 1)
            : StringParse.EMPTY_STR_ARRAY;

        // for (String genericParameter : genericParameters)
        //     this.genericParameters.add(genericParameter);
    }


    // ********************************************************************************************
    // ********************************************************************************************
    // DECLARED METHODS
    // ********************************************************************************************
    // ********************************************************************************************


    /**
     * <EMBED CLASS=defs DATA-DECL=Method DATA-VEC=methods>
     * <EMBED CLASS='external-html' DATA-FILE-ID=PF_ADD_DESC>
     * @param m <EMBED CLASS='external-html' DATA-FILE-ID=PF_ADD_DECL>
     * @see #methods
     */
    protected final void addMethod(Method m) { methods.add(m); }

    /**
     * This is the list of {@link Method} instances identified by the parser for this
     * {@code ParsedFile}
     */
    protected final Vector<Method> methods = new Vector<>();

    /**
     * <EMBED CLASS=defs DATA-DECL=Method DATA-VEC=methods>
     * <EMBED CLASS='external-html' DATA-FILE-ID=PF_NUM_DESC>
     * @return <EMBED CLASS='external-html' DATA-FILE-ID=PF_NUM_RET>
     * @see #methods
     */
    public int numMethods() { return methods.size(); }

    /**
     * <EMBED CLASS=defs DATA-DECL=Method DATA-VEC=methods>
     * <EMBED CLASS='external-html' DATA-FILE-ID=PF_GET_DESC>
     * @param i Index into the {@link #methods} {@code Vector}
     * @return <EMBED CLASS='external-html' DATA-FILE-ID=PF_GET_RET>
     * @see #methods
     */
    public Method getMethod(int i) { return methods.elementAt(i); }

    /**
     * <EMBED CLASS=defs DATA-DECL=Method DATA-VEC=methods>
     * <EMBED CLASS='external-html' DATA-FILE-ID=PF_GET_ALL_DESC>
     * @return <EMBED CLASS='external-html' DATA-FILE-ID=PF_GET_ALL_RET>
     * @see #methods
     */
    public Method[] getMethods() { return methods.toArray(new Method[methods.size()]); }

    /**
     * <EMBED CLASS=defs DATA-DECL=Method DATA-VEC=methods>
     * <EMBED CLASS='external-html' DATA-FILE-ID=PF_CONS_DESC>
     * @param acceptMethodConsumer Any user-provided {@code Consumer}
     * @see #methods
     */
    public void getMethods(Consumer<Method> acceptMethodConsumer)
    { methods.forEach((Method method) -> acceptMethodConsumer.accept(method)); }


    // ********************************************************************************************
    // ********************************************************************************************
    // DECLARED CONSTRUCTORS
    // ********************************************************************************************
    // ********************************************************************************************


    /**
     * <EMBED CLASS=defs DATA-DECL=Constructor DATA-VEC=constructors>
     * <EMBED CLASS='external-html' DATA-FILE-ID=PF_ADD_DESC>
     * @param c <EMBED CLASS='external-html' DATA-FILE-ID=PF_ADD_DECL>
     * @see #constructors
     */
    protected final void addConstructor(Constructor c) { constructors.add(c); }

    /**
     * This is the list of {@link Constructor} instances identified by the parser for this
     * {@code ParsedFile}
     */
    protected final Vector<Constructor> constructors = new Vector<>();

    /**
     * <EMBED CLASS=defs DATA-DECL=Constructor DATA-VEC=constructors>
     * <EMBED CLASS='external-html' DATA-FILE-ID=PF_NUM_DESC>
     * @return <EMBED CLASS='external-html' DATA-FILE-ID=PF_NUM_RET>
     * @see #constructors
     */
    public int numConstructors() { return constructors.size(); }

    /**
     * <EMBED CLASS=defs DATA-DECL=Constructor DATA-VEC=constructors>
     * <EMBED CLASS='external-html' DATA-FILE-ID=PF_GET_DESC>
     * @param i Index into the {@link #constructors} {@code Vector}
     * @return <EMBED CLASS='external-html' DATA-FILE-ID=PF_GET_RET>
     * @see #constructors
     */
    public Constructor getConstructor(int i) { return constructors.elementAt(i); }

    /**
     * <EMBED CLASS=defs DATA-DECL=Constructor DATA-VEC=constructors>
     * <EMBED CLASS='external-html' DATA-FILE-ID=PF_GET_ALL_DESC>
     * @return <EMBED CLASS='external-html' DATA-FILE-ID=PF_GET_ALL_RET>
     * @see #constructors
     */
    public Constructor[] getConstructors()
    { return constructors.toArray(new Constructor[constructors.size()]); }

    /**
     * <EMBED CLASS=defs DATA-DECL=Constructor DATA-VEC=constructors>
     * <EMBED CLASS='external-html' DATA-FILE-ID=PF_CONS_DESC>
     * @param acceptConstructorConsumer Any user-provided {@code Consumer}
     * @see #constructors
     */
    public void getConstructors(Consumer<Constructor> acceptConstructorConsumer)
    {
        constructors.forEach
            ((Constructor constructor) -> acceptConstructorConsumer.accept(constructor));
    }


    // ********************************************************************************************
    // ********************************************************************************************
    // DECLARED FIELDS
    // ********************************************************************************************
    // ********************************************************************************************


    /**
     * <EMBED CLASS=defs DATA-DECL=Field DATA-VEC=fields>
     * <EMBED CLASS='external-html' DATA-FILE-ID=PF_ADD_DESC>
     * @param f <EMBED CLASS='external-html' DATA-FILE-ID=PF_ADD_DECL>
     * @see #fields
     */
    protected final void addField(Field f) { fields.add(f); }

    /**
     * This is the list of {@link Field} instances identified by the parser for this
     * {@code ParsedFile}
     */
    protected final Vector<Field> fields = new Vector<>();

    /**
     * <EMBED CLASS=defs DATA-DECL=Field DATA-VEC=fields>
     * <EMBED CLASS='external-html' DATA-FILE-ID=PF_NUM_DESC>
     * @return <EMBED CLASS='external-html' DATA-FILE-ID=PF_NUM_RET>
     * @see #fields
     */
    public int numFields() { return fields.size(); }

    /**
     * <EMBED CLASS=defs DATA-DECL=Field DATA-VEC=fields>
     * <EMBED CLASS='external-html' DATA-FILE-ID=PF_GET_DESC>
     * @param i Index into the {@link #fields} {@code Vector}
     * @return <EMBED CLASS='external-html' DATA-FILE-ID=PF_GET_RET>
     * @see #fields
     */
    public Field getField(int i) { return fields.elementAt(i); }

    /**
     * <EMBED CLASS=defs DATA-DECL=Field DATA-VEC=fields>
     * <EMBED CLASS='external-html' DATA-FILE-ID=PF_GET_ALL_DESC>
     * @return <EMBED CLASS='external-html' DATA-FILE-ID=PF_GET_ALL_RET>
     * @see #fields
     */
    public Field[] getFields() { return fields.toArray(new Field[fields.size()]); }

    /**
     * <EMBED CLASS=defs DATA-DECL=Field DATA-VEC=fields>
     * <EMBED CLASS='external-html' DATA-FILE-ID=PF_CONS_DESC>
     * @param acceptFieldConsumer Any user-provided {@code Consumer}
     * @see #fields
     */
    public void getFields(Consumer<Field> acceptFieldConsumer)
    { fields.forEach((Field field) -> acceptFieldConsumer.accept(field)); }


    // ********************************************************************************************
    // ********************************************************************************************
    // DECLARED ANNOTATION ELEMENTS (only for annotations)
    // ********************************************************************************************
    // ********************************************************************************************


    /**
     * <EMBED CLASS=defs DATA-DECL=AnnotationElem DATA-VEC=annotationElems DATA-KIND=annotation>
     * <EMBED CLASS='external-html' DATA-FILE-ID=PF_ADD_DESC>
     * @param ae <EMBED CLASS='external-html' DATA-FILE-ID=PF_ADD_DECL>
     * @see #annotationElems
     */
    protected final void addAnnotationElem(AnnotationElem ae)
    { annotationElems.add(ae); }

    /**
     * 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>
     */
    protected final Vector<AnnotationElem> annotationElems = new Vector<>();

    /**
     * <EMBED CLASS=defs DATA-DECL=AnnotationElem DATA-VEC=annotationElems DATA-KIND=annotation>
     * <EMBED CLASS='external-html' DATA-FILE-ID=PF_NUM_DESC>
     * <EMBED CLASS='external-html' DATA-FILE-ID=PF_NOT_POSSIBLE>
     * @return <EMBED CLASS='external-html' DATA-FILE-ID=PF_NUM_RET>
     * @see #annotationElems
     * 
     */
    public int numAnnotationElems() { return annotationElems.size(); }

    /**
     * <EMBED CLASS=defs DATA-DECL=AnnotationElem DATA-VEC=annotationElems DATA-KIND=annotation>
     * <EMBED CLASS='external-html' DATA-FILE-ID=PF_GET_DESC>
     * <EMBED CLASS='external-html' DATA-FILE-ID=PF_NOT_POSSIBLE>
     * @param i Index into the {@link #annotationElems} {@code Vector}
     * @return <EMBED CLASS='external-html' DATA-FILE-ID=PF_GET_RET>
     * @see #annotationElems
     */
    public AnnotationElem getAnnotationElem(int i) { return annotationElems.elementAt(i); }

    /**
     * <EMBED CLASS=defs DATA-DECL=AnnotationElem DATA-VEC=annotationElems DATA-KIND=annotation>
     * <EMBED CLASS='external-html' DATA-FILE-ID=PF_GET_ALL_DESC>
     * <EMBED CLASS='external-html' DATA-FILE-ID=PF_NOT_POSSIBLE>
     * @return <EMBED CLASS='external-html' DATA-FILE-ID=PF_GET_ALL_RET>
     * @see #annotationElems
     */
    public AnnotationElem[] getAnnotationElems()
    { return annotationElems.toArray(new AnnotationElem[annotationElems.size()]); }

    /**
     * <EMBED CLASS=defs DATA-DECL=AnnotationElem DATA-VEC=annotationElems DATA-KIND=annotation>
     * <EMBED CLASS='external-html' DATA-FILE-ID=PF_CONS_DESC>
     * <EMBED CLASS='external-html' DATA-FILE-ID=PF_NOT_POSSIBLE>
     * @param acceptAEConsumer Any user-provided {@code Consumer}
     * @see #annotationElems
     */
    public void getAnnotationElems(Consumer<AnnotationElem> acceptAEConsumer)
    { annotationElems.forEach((AnnotationElem elem) -> acceptAEConsumer.accept(elem)); }


    // ********************************************************************************************
    // ********************************************************************************************
    // DECLARED ENUM CONSTANTS (only for 'enums')
    // ********************************************************************************************
    // ********************************************************************************************


    /**
     * <EMBED CLASS=defs DATA-DECL=EnumConstant DATA-VEC=enumConstants DATA-KIND=enum>
     * <EMBED CLASS='external-html' DATA-FILE-ID=PF_ADD_DESC>
     * <EMBED CLASS='external-html' DATA-FILE-ID=PF_NOT_POSSIBLE>
     * @param ec <EMBED CLASS='external-html' DATA-FILE-ID=PF_ADD_DECL>
     * @see #enumConstants
     */
    protected final void addEnumConstant(EnumConstant ec)
    { enumConstants.add(ec); }

    /**
     * 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
     */
    protected final Vector<EnumConstant> enumConstants = new Vector<>();

    /**
     * <EMBED CLASS=defs DATA-DECL=EnumConstant DATA-VEC=enumConstants DATA-KIND=enum>
     * <EMBED CLASS='external-html' DATA-FILE-ID=PF_NUM_DESC>
     * <EMBED CLASS='external-html' DATA-FILE-ID=PF_NOT_POSSIBLE>
     * @return <EMBED CLASS='external-html' DATA-FILE-ID=PF_NUM_RET>
     * @see #enumConstants
     */
    public int numEnumConstants() { return enumConstants.size(); }

    /**
     * <EMBED CLASS=defs DATA-DECL=EnumConstant DATA-VEC=enumConstants DATA-KIND=enum>
     * <EMBED CLASS='external-html' DATA-FILE-ID=PF_GET_DESC>
     * <EMBED CLASS='external-html' DATA-FILE-ID=PF_NOT_POSSIBLE>
     * @param i Index into the {@link #enumConstants} {@code Vector}
     * @return <EMBED CLASS='external-html' DATA-FILE-ID=PF_GET_RET>
     * @see #enumConstants
     */
    public EnumConstant getEnumConstant(int i) { return enumConstants.elementAt(i); }

    /**
     * <EMBED CLASS=defs DATA-DECL=EnumConstant DATA-VEC=enumConstants DATA-KIND=enum>
     * <EMBED CLASS='external-html' DATA-FILE-ID=PF_GET_ALL_DESC>
     * <EMBED CLASS='external-html' DATA-FILE-ID=PF_NOT_POSSIBLE>
     * @return <EMBED CLASS='external-html' DATA-FILE-ID=PF_GET_ALL_RET>
     * @see #enumConstants
     */
    public EnumConstant[] getEnumConstants()
    { return enumConstants.toArray(new EnumConstant[enumConstants.size()]); }

    /**
     * <EMBED CLASS=defs DATA-DECL=EnumConstant DATA-VEC=enumConstants DATA-KIND=enum>
     * <EMBED CLASS='external-html' DATA-FILE-ID=PF_CONS_DESC>
     * <EMBED CLASS='external-html' DATA-FILE-ID=PF_NOT_POSSIBLE>
     * @param acceptECConsumer Any user-provided {@code Consumer}
     * @see #enumConstants
     */
    public void getEnumConstants(Consumer<EnumConstant> acceptECConsumer)
    { enumConstants.forEach((EnumConstant elem) -> acceptECConsumer.accept(elem)); }


    // ********************************************************************************************
    // ********************************************************************************************
    // DECLARED INNER-CLASSES
    // ********************************************************************************************
    // ********************************************************************************************


    /**
     * <EMBED CLASS=defs DATA-DECL=NestedType DATA-VEC=nestedTypes>
     * <EMBED CLASS='external-html' DATA-FILE-ID=PF_ADD_DESC>
     * @param nt <EMBED CLASS='external-html' DATA-FILE-ID=PF_ADD_DECL>
     * @see #nestedTypes
     */
    protected final void addNestedType(NestedType nt) { nestedTypes.add(nt); }

    /**
     * This is the list of {@link NestedType} instances identified by the parser for this
     * {@code ParsedFile}
     */
    protected final Vector<NestedType> nestedTypes = new Vector<>();

    /**
     * <EMBED CLASS=defs DATA-DECL=NestedType DATA-VEC=nestedTypes>
     * <EMBED CLASS='external-html' DATA-FILE-ID=PF_NUM_DESC>
     * @return <EMBED CLASS='external-html' DATA-FILE-ID=PF_NUM_RET>
     * @see #nestedTypes
     */
    public int numNestedTypes() { return nestedTypes.size(); }

    /**
     * <EMBED CLASS=defs DATA-DECL=NestedType DATA-VEC=nestedTypes>
     * <EMBED CLASS='external-html' DATA-FILE-ID=PF_GET_DESC>
     * @param i Index into the {@link #nestedTypes} {@code Vector}
     * @return <EMBED CLASS='external-html' DATA-FILE-ID=PF_GET_RET>
     * @see #nestedTypes
     */
    public NestedType getNestedType(int i) { return nestedTypes.elementAt(i); }

    /**
     * <EMBED CLASS=defs DATA-DECL=NestedType DATA-VEC=nestedTypes>
     * <EMBED CLASS='external-html' DATA-FILE-ID=PF_GET_ALL_DESC>
     * @return <EMBED CLASS='external-html' DATA-FILE-ID=PF_GET_ALL_RET>
     * @see #nestedTypes
     */
    public Method[] getNestedTypes() { return methods.toArray(new Method[methods.size()]); }

    /**
     * <EMBED CLASS=defs DATA-DECL=NestedType DATA-VEC=nestedTypes>
     * <EMBED CLASS='external-html' DATA-FILE-ID=PF_CONS_DESC>
     * @param acceptNTConsumer Any user-provided {@code Consumer}
     * @see #nestedTypes
     */
    public void getNestedTypes(Consumer<NestedType> acceptNTConsumer)
    { nestedTypes.forEach((NestedType type) -> acceptNTConsumer.accept(type)); }


    // ********************************************************************************************
    // ********************************************************************************************
    // 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(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(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' +
            "name:                 " + name + '\n' +
            "CIET:                 " + ciet + '\n' +
            "packageName:          " + packageName + '\n' +
            "simpleName:           " + simpleName + '\n' +
            "fullyQualifedName:    " + fullyQualifiedName + '\n' +
            "isGeneric:            " + isGeneric + '\n' +
            "Type Parameters:      " + typeParamsStr + '\n' +
            "isInner:              " + isInner + '\n' +
            "Container Classes:    " + containerClassesStr + "\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(getGenericParameters(), 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 ["        + BYELLOW + name                  + RESET + "], " + 
            "Package ["     + BYELLOW + packageName           + RESET + "], " +
            "CIET ["        + BYELLOW + ciet                  + RESET + "]\n" +
            "Qualified ["   + BYELLOW + fullyQualifiedName    + RESET + "], " +
            "Simple ["      + BYELLOW + simpleName            + 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(getGenericParameters(), 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      [" + BYELLOW + name                  + RESET + "]\n" + 
            "Package   [" + BYELLOW + packageName           + RESET + "]\n" +
            "CIET      [" + BYELLOW + ciet                  + RESET + "]\n" +
            "Qualified [" + BYELLOW + fullyQualifiedName    + RESET + "]\n" +
            "Simple    [" + BYELLOW + simpleName            + RESET + "]\n" +
            typeParams +
            m + f + c + ec + ae + nt + '\n';
    }
}