package Torello.JavaDoc;


// *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
// Standard-Java Imports
// *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***

import java.util.*;

import java.io.IOException;
import java.util.function.Consumer;


// *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
// Java-HTML Imports
// *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***

import Torello.Java.*;

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

import Torello.Java.ReadOnly.ReadOnlyList;
import Torello.Java.ReadOnly.ReadOnlyArrayList;
import Torello.Java.ReadOnly.ROArrayListBuilder;
import Torello.Java.Additional.Ret2;


// *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
// The new Source-Code Parser: com.sun.source.*
// *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***

import com.sun.source.util.*;
import com.sun.source.tree.*;
import com.sun.source.doctree.*;


/**
 * <B STYLE='color:darkred;'>Reflection Class:</B>
 * 
 * Common-Root Ancestor Class of all Bridge Data-Classes.
 * 
 * <BR /><BR />
 * <EMBED CLASS='external-html' DATA-FILE-ID=JPB_DECLARATION>
 * <EMBED CLASS='external-html' DATA-FILE-ID=JPB_DIAGRAM>
 */
@JDHeaderBackgroundImg
public abstract class Declaration implements java.io.Serializable
{
    /** <EMBED CLASS='external-html' DATA-FILE-ID=SVUID> */
    public static final long serialVersionUID = 1;

    /**
     * For the purposes of passing these around to different parts of the code, every one of these
     * are given a unique ID.  This id is unique for a method, whether it was parsed from a detail
     * or a summary section.  This id is (probably) not useful outside of the HTML Processor
     * Classes.
     * 
     * <BR /><BR /><B CLASS=JDDescLabel>ID Clone:</B>
     * 
     * <BR />If a subclass of {@code Declaration} is cloned, then this {@code id} field is also
     * cloned / copied.
     */
    public final int id;

    // The id is just created using this counter.
    private static int idCounter = 1;

    // Used for Modifiers and other Empty ReadOnlyLists's of String
    static final ReadOnlyList<String> EMPTY_READONLY_LIST = ReadOnlyList.of();

    /**
     * This returns the {@code String} that is to be sent to the Syntax {@link HiLiter}.  This is
     * the code inserted into the "HiLited Code" Part (at the end) of a Details Entry on a Java-Doc
     * Web Page.
     * 
     * <BR /><BR />On the part of a Java-Doc Web-Page having a "Method Detail", the Method's
     * HiLited Source-Code body is obtained by the Upgrader-Logic using this here method.
     * 
     * <BR /><BR /><B CLASS=JDDescLabel>Sub-Class Return Values:</B>
     * 
     * <BR />This method is overloaded by all sub-classes, and returns values as follows:
     * 
     * <BR /><BR /><UL CLASS=JDUL>
     * <LI>{@link Method} will return its {@link Callable#body} field.</LI>
     * <LI>{@link Constructor} will return its {@link Callable#body} field.</LI>
     * <LI>{@link Field} will return the {@link #signature} field</LI>
     * <LI>{@link EnumConstant} will return the {@link #signature} field</LI>
     * <LI>{@link AnnotationElem} will return the {@link #signature} field</LI>
     * <LI>{@link NestedType} will always return null</LI>
     * </UL>
     * 
     * @return The {@code String} that is ultimately sent to the Syntax HiLiter, and inserted
     * into a Java Doc page.
     * 
     * This is package-private, and isn't useful enough to put into the API - this is used
     * internally, only.
     */
    abstract String codeHiLiteString();


    // ********************************************************************************************
    // ********************************************************************************************
    // Basic String-Fields
    // ********************************************************************************************
    // ********************************************************************************************


    /**
     * The <B>Name</B> of the java {@link Field}, {@link Method}, {@code Constructor},
     * {@link EnumConstant} or {@link AnnotationElem}.  This will be a <B>simple, standard</B>
     * 'Java Identifier'.
     * 
     * <BR /><BR />Note that the name of a {@code Constructor} (for-example) is always just the
     * name of the class.
     * 
     * <BR /><BR />This field will never be null.
     */
    public final String name;

    /**
     * The complete, declared <B>Signature</B> (as a {@code String}) of the {@link Method},
     * {@link Field}, {@link Constructor}, {@link EnumConstant} or {@link AnnotationElem}.
     * 
     * <BR /><BR />This field would never be null.
     */
    public final String signature;

    /**
     * The <B>Java Doc Comment</B> of this <B>'{@link Entity}'</B> ({@link Field}, {@link Method},
     * {@code Constructor}, {@link EnumConstant}, {@link AnnotationElem} or {@link NestedType}) as
     * a {@code String} - if one exists.  The Java Doc Comment is the one defined directly above
     * the {@code Declaration}.
     * 
     * <BR /><BR />If this <CODE>Entity</CODE> / Member ({@code Field, Method, Constructor} etc...)
     * did not have a Java Doc Comment placed on it, <I>then this field {@code 'jdComment'} will be
     * {@code null}.</I>
     */
    public final String jdComment;

    /**
     * The <B>Body</B> of this <B>'{@link Entity}'</B> ({@link Field}, {@link Method},
     * {@code Constructor}, {@link EnumConstant}, {@link AnnotationElem} or {@link NestedType}) as
     * a {@code String} - if one exists.  
     * 
     * <BR /><BR />If this <CODE>Entity</CODE> / Member ({@code Field, Method, Constructor} etc...)
     * did not have a body, <I>then this field {@code 'body'} will be {@code null}.</I>
     * 
     * <BR /><BR />The {@code 'body'} of a {@code Method} or {@code Constructor} is exactly the
     * code that comprises it.  If the method is {@code abstract}, then the method will not have a
     * body, and in such cases this field will be null.  If this member / entity is a {@link Field}
     * then the body is the initializer of the {@code Field}.  Again, if there were no initializer
     * for the field, then {@code 'body'} would also be null.
     */
    public final String body;


    // ********************************************************************************************
    // ********************************************************************************************
    // Non-Basic Fields
    // ********************************************************************************************
    // ********************************************************************************************


    /**
     * This just stores the type of {@link Entity} this is.  For sub-classes instances of
     * {@link Declaration} which are {@link Method}, this field will be equal to
     * {@link Entity#METHOD}.  For instances of the {@link Field} sub-class, this will equal
     * {@link Entity#FIELD}, and so on and so forth.
     * 
     * <BR /><BR />Mostly, this makes code easier to read when used along-side <B>if-statements</B>
     * or <B>switch-statements</B>.  This field somewhat akin to {@code Declaration.getClass()}
     * (when retrieving the specific {@code Declaration} sub-class type).
     * 
     * <BR /><BR /><B CLASS=JDDescLabel>Reminder:</B>
     * 
     * <BR />Both this class, and sub-class {@code Callable} are declared {@code abstract}, and
     * only instances of Method, Field, Constructor, etc... can be instantiated.  Only
     * non-{@code abstract} implementations of this class need to worry about assigning this field
     * to any real-value.
     */
    public final Entity entity;

    /** Location instance that contains character-locations within the original Java Source-File */
    public final Location location;


    // ********************************************************************************************
    // ********************************************************************************************
    // ReadOnlyList<String> Fields
    // ********************************************************************************************
    // ********************************************************************************************


    /**
     * The {@code 'modifiers'} placed on this {@code Declaration}, including {@code String's}
     * such as: {@code public, static, final} etc...
     */
    public ReadOnlyList<String> modifiers;

    /** <EMBED CLASS='external-html' DATA-FILE-ID=JPB_DECL_ANNOT> */
    public ReadOnlyList<String> annotations;


    // ********************************************************************************************
    // ********************************************************************************************
    // Constructor - com.sun.source.tree 
    // ********************************************************************************************
    // ********************************************************************************************


    // package-private: Only used by subclasses.
    Declaration(
            TreeUtils       util,
            Tree            tree,
            ModifiersTree   mt,
            String          name,
            Entity          entity,
            Tree            body
        )
    {
        // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
        // Pre-Liminary
        // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***

        this.id                 = idCounter++;
        this.name               = name;
        this.entity             = entity;


        // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
        // The Annotations Placed on this Declaration
        // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
        //
        // NOTE: For EnumConstant's, the passed Modifiers-Tree is just null!

        // List<? extends AnnotationTree> annotList = ...
        @SuppressWarnings("unchecked")
        List<AnnotationTree> annotList = (mt == null)
            ? null
            : (List<AnnotationTree>) mt.getAnnotations();

        if ((annotList == null) || (annotList.size() == 0))
            this.annotations = EMPTY_READONLY_LIST;

        else this.annotations = new ReadOnlyArrayList<String>
            (annotList, (AnnotationTree at) -> at.toString().trim(), annotList.size());


        // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
        // The Modifiers that Flag this Declaration (private, public, static, final, etc...)
        // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
        //
        // NOTE: For EnumConstant's, the passed Modifiers-Tree is just null!

        Set<javax.lang.model.element.Modifier> modSet = (mt == null)
            ? null
            : mt.getFlags();

        if ((modSet == null) || (modSet.size() == 0))
            this.modifiers = EMPTY_READONLY_LIST;

        else this.modifiers = new ReadOnlyArrayList<String>
            (modSet, (javax.lang.model.element.Modifier m) -> m.toString().trim(), modSet.size());


        // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
        // Location
        // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***

        this.location = (entity == Entity.INNER_CLASS)

            ? new Location(util, tree, util.getJavaDocCommentTree(tree))

            : new Location(
                util, tree, util.getJavaDocCommentTree(tree), body,
                (entity == Entity.FIELD) ? body : null
            );


        // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
        // Now the String's
        // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***

        this.signature = util.srcFileAsStr.substring
            (this.location.signatureStartPos, this.location.signatureEndPos);

        this.jdComment = (this.location.jdcStartPos == -1)
            ? null
            : util.srcFileAsStr.substring(this.location.jdcStartPos, this.location.jdcEndPos);

        this.body = (this.location.bodyStartPos == -1)
            ? null
            : util.srcFileAsStr.substring(this.location.bodyStartPos, this.location.bodyEndPos);
    }


    // ********************************************************************************************
    // ********************************************************************************************
    // Constructor - synthetic methods
    // ********************************************************************************************
    // ********************************************************************************************


    // Used only by the Callable Subclass, for building instances of derived/synthetic methods
    // and constructors.  (For instance, an enum has 'valueOf()' and 'values()')
    // These methods do not have a location or a jdComment or even a body to hilite

    Declaration(String name, Entity entity, String signature)
    {
        this.id             = idCounter++;
        this.name           = name;
        this.entity         = entity;
        this.modifiers      = EMPTY_READONLY_LIST;
        this.annotations    = EMPTY_READONLY_LIST;
        this.signature      = signature;

        // Since this constructor is only used for "Synthetic Methods" (barely ever used), it is no
        // big deal to just assign these null;

        this.location   = null;
        this.jdComment  = null;
        this.body       = null;
    }

    // Not private - used by sub-classes
    Declaration(Declaration d)
    {
        this.id                 = d.id;
        this.annotations        = d.annotations;
        this.modifiers          = d.modifiers;
        this.name               = d.name;
        this.signature          = d.signature;
        this.jdComment          = d.jdComment;
        this.body               = d.body;
        this.entity             = d.entity;
        this.location           = d.location;
    }


    // ********************************************************************************************
    // ********************************************************************************************
    // Package-Private toString-HELPERS: Used by all subclasses 'toString(int flags)' methods
    // ********************************************************************************************
    // ********************************************************************************************


    Ret2<Boolean, Boolean> jowFlags(int flags)
    {
        boolean onlyJOW         = (flags & JOW_INSTEAD) > 0;
        boolean addJOW          = (flags & JOW_ALSO) > 0;

        // "onlyJOW" has a higher FLAG-PRECEDENCY
        if (onlyJOW && addJOW) addJOW = false;

        return new Ret2<>(addJOW, onlyJOW);
    }

    String printedName(String entity, int numSpaces, boolean color)
    {
        return
            StringParse.rightSpacePad(entity + " Name:", numSpaces) +
            "[" + (color ? BCYAN : "") + name + (color ? RESET : "") + "]\n";
    }

    String printedSignature(int numSpaces, boolean color)
    {
        return
            StringParse.rightSpacePad("Signature:", numSpaces) +
            "[" + (color ? BYELLOW : "") +
            StrPrint.abbrevEndRDSF(signature, MAX_STR_LEN, true) +
            (color ? RESET : "") + "]\n";
    }

    String printedDeclaration(int numSpaces, boolean color)
    {
        return
            StringParse.rightSpacePad("Declaration:", numSpaces) +
            "[" + (color ? BYELLOW : "") +
            StrPrint.abbrevEndRDSF(signature, MAX_STR_LEN, true) +
            (color ? RESET : "") + "]\n";
    }

    String printedModifiers(int numSpaces)
    {
        return
            StringParse.rightSpacePad("Modifiers:", numSpaces) +
            "[" + StrCSV.toCSV(modifiers, true, true, null) + "]\n";
    }

    String printedComments(int numSpaces, boolean color, boolean comments)
    {
        if (! comments)
            return "";

        else if (jdComment == null) return
            "\n" +
            StringParse.rightSpacePad("JD Comments:", numSpaces) +
            (color ? BRED : "") + "None Available / Not Included" + (color ? RESET : "");

        else return
            "\n" +
            StringParse.rightSpacePad("JD Comments:", numSpaces) +
            "[" +
            (color ? BGREEN : "") +
            StrPrint.abbrevEndRDSF(jdComment, MAX_STR_LEN, true) +
            (color ? RESET : "") +
            "]";
    }

    // NOTE: This is always the last item printed to the output-string.  This line *DOES NOT* end
    //       with a new-line '\n' character.

    String printedLocation(int numSpaces, boolean color, boolean briefLocation)
    {
        if (location == null) return StringParse.rightSpacePad("Location:", numSpaces) + "null";

        if (briefLocation) return color
            ?
                (StringParse.rightSpacePad("Location:", numSpaces) +
                "[" +
                "signature-line=" + BRED + this.location.signatureStartLine + RESET + ", " +
                "javadoc-line=" + BRED + this.location.jdcStartLine + RESET + ", " +
                "body-line=" + BRED + this.location.bodyStartLine + RESET +
                "]")
            :
                (StringParse.rightSpacePad("Location:", numSpaces) +
                "[" +
                "signature-line=" + this.location.signatureStartLine + ", " +
                "javadoc-line=" + this.location.jdcStartLine + ", " +
                "body-line=" + this.location.bodyStartLine +
                ']');

        String spaces = StringParse.nChars(' ', numSpaces);

        if (color) return
            StringParse.rightSpacePad("Location:", numSpaces) +
            "JavaDocComment: [" +
                "startPos=" + BRED + location.jdcStartPos + RESET + ", " +
                "endPos=" + BRED + location.jdcEndPos + RESET + ", " +
                "startLine=" + BRED + location.jdcStartLine + RESET + ", " +
                "endLine=" + BRED + location.jdcEndLine + RESET + ", " +
                "startCol=" + BRED + location.jdcStartCol + RESET + ", " +
                "endCol=" + BRED + location.jdcEndCol + RESET + "]\n" +

            spaces + "Signature:      [" +
                "startPos=" + BRED + location.signatureStartPos + RESET + ", " +
                "endPos=" + BRED + location.signatureEndPos + RESET + ", " +
                "startLine=" + BRED + location.signatureStartLine + RESET + ", " +
                "endLine=" + BRED + location.signatureEndLine + RESET + ", " +
                "startCol=" + BRED + location.signatureStartCol + RESET + ", " +
                "endCol=" + BRED + location.signatureEndCol + RESET + "]\n" +

            spaces + "Body:           [" +
                "startPos=" + BRED + location.bodyStartPos + RESET + ", " +
                "endPos=" + BRED + location.bodyEndPos + RESET + ", " +
                "startLine=" + BRED + location.bodyStartLine + RESET + ", " +
                "endLine=" + BRED + location.bodyEndLine + RESET + ", " +
                "startCol=" + BRED + location.bodyStartCol + RESET + ", " +
                "endCol=" + BRED + location.bodyEndCol + RESET + "]";

        else return
            StringParse.rightSpacePad("Location:", numSpaces) +
            "JavaDocComment: [" +
                "startPos=" + location.jdcStartPos + ", " +
                "endPos=" + location.jdcEndPos + ", " +
                "startLine=" + location.jdcStartLine + ", " +
                "endLine=" + location.jdcEndLine + ", " +
                "startCol=" + location.jdcStartCol + ", " +
                "endCol=" + location.jdcEndCol + "]\n" +

            spaces + "Signature:      [" +
                "startPos=" + location.signatureStartPos + ", " +
                "endPos=" + location.signatureEndPos + ", " +
                "startLine=" + location.signatureStartLine + ", " +
                "endLine=" + location.signatureEndLine + ", " +
                "startCol=" + location.signatureStartCol + ", " +
                "endCol=" + location.signatureEndCol + "]\n" +

            spaces + "Body:           [" +
                "startPos=" + location.bodyStartPos + ", " +
                "endPos=" + location.bodyEndPos + ", " +
                "startLine=" + location.bodyStartLine + ", " +
                "endLine=" + location.bodyEndLine + ", " +
                "startCol=" + location.bodyStartCol + ", " +
                "endCol=" + location.bodyEndCol + "]";
    }


    // ********************************************************************************************
    // ********************************************************************************************
    // Abstract-Class ToString
    // ********************************************************************************************
    // ********************************************************************************************


    /**
     * Dummy Method.  Overriden by Concrete Sub-Classes.
     * @see Method#toString()
     * @see Field#toString()
     * @see Constructor#toString()
     */
    public String toString()
    { return "Declaration is Abstract, all Concrete Sub-Classes Override this method."; }

    /**
     * Dummy Method.  Overriden by Concrete Sub-Classes.
     * @see Method#toString(int)
     * @see Field#toString(int)
     * @see Constructor#toString(int)
     */
    public String toString(int flags)
    { return "Declaration is Abstract, all Concrete Sub-Classes Override this method."; }
}