package Torello.JavaDoc;


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

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


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

import Torello.Java.*;

import static Torello.JavaDoc.PF.*;

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


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

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


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

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


    // ********************************************************************************************
    // ********************************************************************************************
    // Public Fields: Param-Expressions
    // ********************************************************************************************
    // ********************************************************************************************


    /**
     * The parameters passed to the constructor that constructed the enumerated-constant instance.
     * 
     * <BR /><BR />Many {@code enum's} do not usually use constructors for their constants - using
     * a constructor is an extra-feature that allows other, informational data to be ascribed to
     * the constant.  If no constructor was used, then there (obviously) couldn't have been any
     * expressions passed to a constructor for the constant.  In such cases, this field will be
     * null.
     */
    public final ReadOnlyList<String> paramExpressions;


    // ********************************************************************************************
    // ********************************************************************************************
    // 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 EnumConstant} instance, it may be retrieved from this
     * {@code transient} field.
     * 
     * <BR /><BR /><B>NOTE:</B> The package {@code com.sun.source.tree} "reuses" or "overloads" the
     * {@code VariableTree} object such that it may represent either a Field, or an Enumerated
     * Constant.
     */
    public final transient VariableTree variableTree;


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


    /**
     * <EMBED CLASS="defs" DATA-KIND=EnumConstant 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 EnumConstant(VariableTree vt, TreeUtils util)
    {
        super(
            util,                       // TreeUtils instance (contains all the parser and stuff)
            vt,                         // 'Tree' instance
            null,                       // ModifiersTree: Annotations on the Field & key-words
                                        //
                                        // TO-DO: ********  RESEARCH THIS, MAYBE FIX THIS ********
                                        // HERE - THE PRESUMPTION IS THAT AN ANNOTATION MAY NOT BE
                                        // PLACED ON AN ENUM-CONSTANT - AND THEREFORE, NEITHER THE
                                        // MODIFIERS NOR THE ANNOTATIONS ARE RELEVANT!!
                                        // *******************************************************
            vt.getName().toString(),    // Name of the Field
            // vt.toString().trim(),    // Signature
            Entity.ENUM_CONSTANT,       // Entity
            null                        // Pass 'null' to the 'body' tree-node
        );

        // List<? extends ExpressionTree> args = ...
        @SuppressWarnings("unchecked")
        List<ExpressionTree> args =
            (List<ExpressionTree>) ((NewClassTree) vt.getInitializer()).getArguments();

        if ((args == null) || (args.size() == 0))
            this.paramExpressions = EMPTY_READONLY_LIST;

        else this.paramExpressions = new ReadOnlyArrayList<String>
            (args, (ExpressionTree et) -> et.toString().trim(), args.size());

        // Reference Hooks: This was built using the com.sun.source.tree.VariableTree class, so
        // there  simply isn't a com.github.javaparser.ast.body.EnumConstantDeclaration (so it is
        // set to null)

        this.variableTree = vt;
    }


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


    /**
     * Generates a {@code String} of this {@code Enum Constant}, with all information included.
     * 
     * @return A printable {@code String} of this {@code EnumConstant}.
     * 
     * @see StrCSV#toCSV(String[], boolean, boolean, Integer)
     * @see #toString(int)
     */
    public String toString()
    {
        return
            "Name:        [" + name + "]\n" +
            "Declaration: [" + StrPrint.abbrevEndRDSF(signature, MAX_STR_LEN, true) + "]\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 EnumConst}, with all information included. This
     * will also included any content requested by the {@code 'flags'} parameter.  For this class
     * ({@code EnumConstant}), 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 AnnotationElem}.
     * 
     * @see PF
     * @see StrCSV#toCSV(String[], boolean, boolean, Integer)
     * @see #toString()
     */
    public String toString(int flags)
    {
        boolean color = (flags & UNIX_COLORS) > 0;

        return
            printedName("Enum-Const", 17, color) + 
            printedDeclaration(17, color) +
            printedParamExpressions(17) +
            printedLocation(17, 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(17, color, (flags & JAVADOC_COMMENTS) > 0);
    }

    private String printedParamExpressions(int LEN)
    {
        if ((paramExpressions == null) || (paramExpressions.size() == 0))
            return "";

        return StringParse.rightSpacePad("Initializer:", LEN) +
            "[" + StrCSV.toCSV(paramExpressions, false, false, null) + "]\n";
    }


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


    /**
     * Java's {@code interface Comparable<T>} requirements.  This does a very simple comparison
     * using the two constants' {@code 'name'} field.
     * 
     * @param ec Any other {@code EnumConstant} to be compared to {@code 'this' EnumConstant}
     * 
     * @return An integer that fulfills Java's
     * {@code interface Comparable<EnumConstant> public boolean compareTo(EnumConstant ec)}
     * method requirements.
     */
    public int compareTo(EnumConstant ec)
    { return (this == ec) ? 0 : this.name.compareTo(ec.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 constant defined.
     * The presumption here is that the definition of an 'constant' only has meaning - <I>at
     * all</I> - inside the context of an {@code enum} where that constant has been defined.  Since
     * inside any {@code '.java'} {@code enum}, there may only be one element with a given name,
     * this method shall return {@code TRUE} whenever the constant being compared also has the same
     * name.
     * 
     * @param other This may be any other {@code EnumConstant}.  It is <I><B>strongly
     * suggested</B></I> that {@code 'other'} be a {@code constant} defined in the same
     * {@code '.java'} source-code file as {@code 'this'} constant.
     * 
     * @return This method returns {@code TRUE} when {@code 'this'} instance of
     * {@code EnumConstant} has the same {@code 'name'} as the name of input-parameter
     * {@code 'other'}
     */
    public boolean equals(EnumConstant other)
    { return this.name.equals(other.name); }
}