package Torello.JavaDoc;


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

import java.io.IOException;
import java.util.Optional;


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

import Torello.Java.*;

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


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

import com.sun.source.tree.Tree;
import com.sun.source.tree.VariableTree;
import com.sun.source.tree.ExpressionTree;


/**
 * 
 * <B STYLE='color:darkred;'>Reflection Class:</B>
 * 
 * Holds all information extracted from <CODE>'&#46;java'</CODE> Source-Files about Field's
 * identified in that file.
 * 
 * <EMBED CLASS='external-html' DATA-FILE-ID=JPB_GET_INST>
 * <EMBED CLASS='external-html' DATA-FILE-ID=JPB_FIELD>
 * <EMBED CLASS='external-html' DATA-FILE-ID=JPB_DIAGRAM>
 */
@JDHeaderBackgroundImg(EmbedTagFileID={"REFLECTION_EXTENSION"})
public class Field extends Declaration
    implements java.io.Serializable, Comparable<Field>, Cloneable
{
    /** <EMBED CLASS='external-html' DATA-FILE-ID=SVUID> */
    protected static final long serialVersionUID = 1;

    @Override
    String codeHiLiteString() { return this.signature; }


    // ********************************************************************************************
    // ********************************************************************************************
    // Public Fields: The Type, and the Initializer
    // ********************************************************************************************
    // ********************************************************************************************


    /** The definition of this field, as a {@code String}. */
    public final String definition;

    /** The type / class of this field, as a {@code String}. */
    public final String type;

    /**
     * The type / class of this field, as a {@code String}.<BR /><BR />
     * <EMBED CLASS='external-html' DATA-FILE-ID=JPB_JOW_TITLE>
     */
    public final String typeJOW;


    // ********************************************************************************************
    // ********************************************************************************************
    // Reference-Hook: com.sun.source.tree
    // ********************************************************************************************
    // ********************************************************************************************


    /**
     * <EMBED CLASS='external-html' DATA-FILE-ID=SSTB_HOOK_FIELD>
     * 
     * If a user decides to make use of the native Sun/Oracle {@code VariableTree} instance that
     * was used to build this {@code Field} instance, it may be retrieved from this
     * {@code transient} field.
     */
    public final transient VariableTree variableTree;


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


    /**
     * <EMBED CLASS="defs" DATA-KIND=Field DATA-ENTITY=VariableTree>
     * <EMBED CLASS='external-html' DATA-FILE-ID=RC_DESCRIPTION>
     * @param vt <EMBED CLASS='external-html' DATA-FILE-ID=RC_PARAM_TREE>
     * @param util <EMBED CLASS='external-html' DATA-FILE-ID=RC_PARAM_UTIL>
     */
    public Field(VariableTree vt, TreeUtils util)
    {
        super(
            util,                       // TreeUtils instance (contains all the parser and stuff)
            vt,                         // 'Tree' instance
            vt.getModifiers(),          // ModifiersTree: Annotations on the Field & key-words
            vt.getName().toString(),    // Name of the Field
            Entity.FIELD,               // Entity
            vt.getInitializer()         // NEW: Pass the initializer to the 'body' tree-node
        );

        this.type       = vt.getType().toString();
        this.typeJOW    = StrSource.typeToJavaIdentifier(this.type);

        ExpressionTree initializer = vt.getInitializer();

        this.definition = (initializer == null) ? null : util.substring(initializer).trim();

        // Reference Hook: This was built using the com.sun.source.tree.VariableTree class
        this.variableTree = vt;
    }


    // ********************************************************************************************
    // ********************************************************************************************
    // Constructor: Used Internally by SignatureParse
    // ********************************************************************************************
    // ********************************************************************************************


    // Ensures that the Version with longer type-information strings is used.
    // Java Doc often uses longer type strings than is available from the source-code parse
    // Remember, JavaParser Symbol-Solver doesn't work well, and the Sun/Oracle Parser doesn't have
    // a linker at all.

    public Field(Field fFromSourceParser, Field fFromHTMLParser)
    {
        // Calls the super 'clone' constructor for Declaration
        // Java Parser has much more information for everything, except the "Type"
        // JP elects to leave off the "Package Information" for types - while Java Doc includes
        // it (**unless** it can provide an <A HREF=...> for the type, then it leaves it off too!)

        super(fFromSourceParser);

        // Continuing with: "JP has this info", while Java Doc just leaves this blank.
        this.definition = fFromSourceParser.definition;

        // Java Doc always produces "java.lang.String", while JP just gives "String"
        ///
        // REMEMBER: JP is lazy when it comes to "Package Information" for types.
        //           Java-Doc includes it often - BUT NOT ALWAYS.  (See above comment)
        //
        // Remember, though, the rest of the JavaParser fields are filled out, Java Doc
        // leaves out all the other information that JP retrieves.

        this.type =
            (fFromHTMLParser.type.length() > fFromSourceParser.type.length())
                ? fFromHTMLParser.type
                : fFromSourceParser.type;

        // This should never matter.  They must be identical.
        this.typeJOW        = fFromSourceParser.typeJOW;
        this.variableTree   = fFromSourceParser.variableTree;
    }


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


    /**
     * Generates a {@code String} of this field, with all information included.
     * 
     * @return A printable {@code String} of this field.
     * 
     * @see StrCSV#toCSV(String[], boolean, boolean, Integer)
     * @see #toString(int)
     */
    public String toString()
    {
        String defStr = (definition == null)
            ? "null" 
            : StrPrint.abbrevEndRDSF(definition, MAX_STR_LEN, true);

        return
            "Name:         [" + name + "]\n" +
            "Declaration:  [" + StrPrint.abbrevEndRDSF(signature, MAX_STR_LEN, true) + "]\n" +
            "Type:         [" + type + "]\n" + 
            "Definition:   [" + defStr + "]\n" +
            "Modifiers:    [" + StrCSV.toCSV(modifiers, true, true, null) + "]\n" +

            // This will **NEVER** be null - unless 'this' instance was built from an HTML File,
            // rather than a source-code file.  Instances like that are only used temporarily, and
            // are garbage collected instantly.  Do this check anyway (just in case).

            "Location:     " + ((this.location == null)
                ? "null" 
                : ('[' + this.location.quickSummary() + ']'));
    }

    /**
     * Generates a {@code String} of this {@code field}, with all information included.  This will
     * also included any content requested by the {@code 'flags'} parameter.  For this class
     * ({@code class Field}), the only additional information printed by this {@code 'toString'}
     * method is the Java-Doc Comment {@code String}.
     * 
     * <BR /><BR />This {@code String} may also have UNIX color codes added.
     * 
     * @param flags These are the {@code toString(...)} flags from class {@code PF}
     * ("Print Flags"). View available flags listed in class {@link PF}.
     * 
     * @return A printable {@code String} of this {@code Field}.
     * 
     * @see PF
     * @see StrCSV#toCSV(String[], boolean, boolean, Integer)
     * @see #toString()
     */
    public String toString(int flags)
    {
        boolean color = (flags & UNIX_COLORS) > 0;

        return
            printedName("Field", 15, color) + 
            printedDeclaration(15, color) +
            printedType(jowFlags(flags)) +
            printedDefinition(color) +
            printedModifiers(15) +
            printedLocation(15, color, (flags & BRIEF_LOCATION) > 0) +

            // The previous method does not add a '\n' end to the end of the returned string
            // This is optional, it adds a '\n' AT THE BEGINNING if it is included

            printedComments(15, color, (flags & JAVADOC_COMMENTS) > 0);
    }

    private String printedType(Torello.Java.Additional.Ret2<Boolean, Boolean> jow)
    {
        if (jow.a /*add-JOW*/)
            return
                "Type:          [" + type + "]\n" +
                "Type-JOW:      [" + typeJOW + "]\n";
        else if (jow.b /*only-JOW*/)
            return  "Type-JOW:      [" + typeJOW + "]\n";
        else
            return  "Type:          [" + type + "]\n";
    }

    private String printedDefinition(boolean color)
    {
        return (definition == null)
            ? "Definition:    [null]\n"
            : "Definition:    [" +
                (color ? BGREEN : "") +
                StrPrint.abbrevEndRDSF(definition, MAX_STR_LEN, true) +
                (color ? RESET : "") + "]\n";
    }


    // *************************************************************************************
    // *************************************************************************************
    // CompareTo & Equals Stuff
    // *************************************************************************************
    // *************************************************************************************


    /**
     * Java's {@code interface Comparable<T>} requirements.  This does a very simple comparison
     * using the two field's {@code 'name'} field.
     * 
     * @param f Any other {@code Field} to be compared to {@code 'this' Field}
     * 
     * @return An integer that fulfills Java's
     * {@code interface Comparable<Field> public boolean compareTo(Field f)} method requirements.
     */
    public int compareTo(Field f)
    { return (this == f) ? 0 : this.name.compareTo(f.name); }

    /**
     * This <I>should be called an "atypical version" of </I> the usual {@code equals(Object
     * other)} method.  This version of equals merely compares the name of the field defined.  The
     * presumption here is that the definition of a 'field' only has meaning - <I>at all</I> -
     * inside the context of a {@code class, interface, } or {@code enumerated-type} where that
     * field is defined.  Since inside any {@code '.java'} source-code file, there may only be one
     * field with a given name, this method shall return {@code TRUE} whenever the field being
     * compared also has the same name.
     * 
     * @param other This may be any other field.  It is <I><B>strongly suggested</B></I> that
     * {@code 'other'} be a field defined in the same {@code '.java'} source-code file as
     * {@code 'this'} field.
     * 
     * @return This method returns {@code TRUE} when {@code 'this'} instance of {@code Field} has
     * the same {@code 'name'} as the name-field of input-parameter {@code 'other'}
     */
    public boolean equals(Field other)
    { return this.name.equals(other.name); }
}