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;


// *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
// JDUInternal
// *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***

import Torello.JDUInternal.Annotations.ReflAnnotations.ReflAnnotationData;


// *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
// 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 CLASS=JDDescLabel>Reflection Class:</B>
 * 
 * <BR />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>
 */
@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 (or most) {@code enum's} do not actually use a constructor for their
     * constants.  Using a constructor is an extra-feature that allows additional information / 
     * data to be ascribed to the constant.
     * 
     * <BR /><BR />If no constructor has been used to buid an Enumerated Constant, then there
     * (obviously) wouldn't be any expressions passed to a constructor for that constant.  In such
     * cases, this field will contain a non-null, empty, {@code ReadOnlyList<String>}.
     */
    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 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 CLASS=JDDescLabel>{@code MethodTree} Note:</B>
     * 
     * <BR />The package {@code com.sun.source.tree} "reuses" or "overloads" the
     * {@code VariableTree} class in that it may represent either a Field, or an
     * Enumerated-Constant.
     */
    public final transient VariableTree variableTree;


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


    // public, but internally-used-ONLY Constructor
    public EnumConstant(
            final VariableTree          vt,
            final ReflAnnotationData    rad,
            final TreeUtils             util
        )
    {
        super(
            rad,    // Stuff for building ReflAnnotationMirrors
            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 #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() + ']'));
    }

    /**
     * <EMBED CLASS='external-html' DATA-FILE-ID=TO_STR_PF>
     * 
     * <BR /><BR />There is additional information printed by this {@code 'toString'} method
     * (versus the zero-argument, standard, Java {@code 'toString'}).  This method will print any
     * available Java-Doc Comment's that were placed on this {@code EnumConstant}.
     * 
     * <BR /><BR />This {@code 'toString'} also allows for adding UNIX-Terminal color codes.
     * 
     * @param flags These are defined in the {@link PF Print-Flags} class
     * @return A printable {@code String} of this {@code EnumConstant}.
     * @see PF
     * @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' {@link #name} field.
     * 
     * @param ec Any other {@code EnumConstant} to be compared to {@code 'this' EnumConstant}
     * 
     * @return An integer that fulfills Java's {@code Comparable<EnumConstant>} interface
     * 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); }
}