package Torello.JavaDoc.Annotations;

import static Torello.Java.C.BCYAN;
import static Torello.Java.C.BRED;
import static Torello.Java.C.RESET;

import Torello.Java.ReadOnly.ReadOnlyList;
import Torello.Java.ReadOnly.ReadOnlySet;

import Torello.Java.StringParse;

import Torello.JavaDoc.Entity;

import Torello.JavaDoc.Messager.Messager;
import Torello.JavaDoc.Messager.MsgPrintTools;
import Torello.JavaDoc.Messager.Where_Am_I;
import Torello.JDUInternal.Miscellaneous.Where.JDUAnnotations;

import com.sun.source.tree.AnnotationTree;
import com.sun.source.tree.ExpressionTree;
import com.sun.source.tree.AssignmentTree;
import com.sun.source.tree.LiteralTree;

import java.util.List;

//     public String    handle();
//     public String    typeName()      default "";
//     public Entity    entity();
//     public String    name();
//     public byte      paramCount()    default -1;
//     public String[]  paramNames()    default { };
//     public String[]  paramTypesJOW() default { };
// 
// The following files are relatedf to this Annotation-Mirror Data-Class:
// 
// package Torello.JDUInternal.Features.LINK_JAVA_SOURCE
//      This package does the "vast majority" of the work that is needed process a User's
//      Annotation-Placement.  The classes in the packages in this class look for, and load, all 
//      of the External '.java'-Files which have been specified by the programmer's annotation
//      uses.  These classes also perform the Source-Code HiLiting, and save the output to the
//      appropriate packge's '[pkg-javadoc]/ljs-hilite-files/' directory.  They finally, also,
//      generate the appropriate "HREF=..." so that an appropriate '<A HREF...>' link may be
//      inserted

/**
 * An internally used data-record class used for storing all user-supplied annotation data 
 * associated with a single use / application of the {@link LinkJavaSource} annotation.
 * 
 * @see Torello.JavaDoc.Annotations.LinkJavaSource
 */
@Torello.JavaDoc.Annotations.JDHeaderBackgroundImg(EmbedTagFileID="MIRROR_JDHBI")
public class LJSMirror implements AnnotationMirror
{
    // ********************************************************************************************
    // ********************************************************************************************
    // Static-Constant Fields
    // ********************************************************************************************
    // ********************************************************************************************


    private static final Where_Am_I WHERE_AM_I = JDUAnnotations.LJSMirror;

    private static final ECData<Torello.JavaDoc.Entity> ecParser = new ECData<>(
        Torello.JavaDoc.Entity.class,
    
        // These are strictly needed for Error message which are being passed to the messager
        JDUAnnotations.LJSMirror,               // Where_Am_I 
        LinkJavaSource.class.getSimpleName(),   // The name of the Annoation
        "entity"                                // The Annotation-Element being processed
    );


    // ********************************************************************************************
    // ********************************************************************************************
    // interface AnnotationMirror
    // ********************************************************************************************
    // ********************************************************************************************


    // Stores the actual text of the @StaticFunctional annotation which was placed.
    // This is nothing more than the exact line that was originally inserted into the class.
    // The only reason this is even needed (in case you are wondering) is because the error 
    // checking & error printing code outputs this text when printing an error message.

    private final String annotationAsStr;

    /** {@inheritDoc} */ @Override
    public String getAnnotationAsString() { return annotationAsStr; }

    /** {@inheritDoc} */ @Override
    public String getAnnotationName() { return "LJSMirror"; }


    // ********************************************************************************************
    // ********************************************************************************************
    // Public, Final, ReadOnly, Mirrored Fields
    // ********************************************************************************************
    // ********************************************************************************************


    /** Holds data extracted from {@link LinkJavaSource#handle()} */
    public final String handle;

    /** Holds data extracted from {@link LinkJavaSource#typeName()} */
    public final String typeName;

    /** Holds data extracted from {@link LinkJavaSource#entity()} */
    public final Entity entity;

    /** Holds data extracted from {@link LinkJavaSource#name()} */
    public final String name;

    /** Holds data extracted from {@link LinkJavaSource#paramCount()} */
    public final Byte paramCount;

    /** Holds data extracted from {@link LinkJavaSource#paramNames()} */
    public final ReadOnlyList<String> paramNames;

    /** Holds data extracted from {@link LinkJavaSource#paramTypesJOW()} */
    public final ReadOnlyList<String> paramTypesJOW;

    /**
     * Assigned {@code TRUE} if and only if {@link #handle} is the only annotation element that
     * has been assigned a value.
     */
    public final boolean hrefOnlyNoLineNum;


    // ********************************************************************************************
    // ********************************************************************************************
    // Package-Private Constructor, Invoked by class "EntityAnnotationMirrors"
    // ********************************************************************************************
    // ********************************************************************************************


    // This is invoked by the top-level mirror-class: EntityAnnotationMirrors
    // ReflAnnotationMirros is in this package, and therefore, this constructor is
    // package private.
    // 
    // This constructor was entirely created by Chat-GPT.
    // Yes, it has been thoroughly tested!
    // Yes, it's the fun of it all that makes ChatGPT worth it.
    // 
    // I have changed it many times since writing that comment.  Not a lot though!
    // I don't bother messing with the A.I. for the "Error-Checking" code.  The truth of it all is
    // that if you approach Chat-GPT like a puzzle, just like programming usually feels like
    // EXCEPT that the challenge is thinking how to describe what you want to do in English, rather
    // than in Java-Code - watching it output your code is sort of enjoyable...
    // 
    // Anything that involves the Messager, I simply cannot think of the English words to explain
    // what I want it to do.  I wouldn't bother asking Mr. GPT about it at all, because it wouldn't
    // even be fun...  The Messager / Error-Checking stuff truly is some of the toughest stuff to
    // write of all.
    //
    // ********************************************************************************************
    // ********************************************************************************************
    //
    // Data-Flow I think I have mastered.  Generally, with data-flow, there are two rules:
    // 
    //      a) 'final' and ReadOnly answer many of the problems you face...  It doesn't change!
    //          No matter what you do with it, or where you send, it cannot change, it was declared
    //          **BOTH** final **AND** ReadOnly - it is just a "Lookup Operation"
    // 
    //      b) Consistent VARIABLE / FIELD NAMES ... answer the rest of your problems
    //         It is **ALWAYS** named "jdhf" (all-lower-case), no matter where in the code you are!
    // 
    //         A JavaSourceCodeFile is **ALWAYS** named 'jscf'
    //         A 'jdhf' can change, a 'jscf' is 100% final-Read-Only...
    //
    // And that is literally it!  Pick a name for your class, and no matter where in the code you
    // need or would like to reference that class, alway use the same field or variable name for
    // that class ... And that is all you need to say about "Data-Flow"...  
    //
    // Again: It's constant / unchanging... It's all just "table lookup"
    //        It always has the same exact name, no matter where it is...  And nothing about the
    //        data is being modified, so it doesn't really matter what you do with the reference,
    //        you cannot change it's values since they are final-read-only!
    // 
    //        I don't have to care what happens to the contents of an object when I pass off a 
    //        reference in my code...
    //
    // ********************************************************************************************
    // ********************************************************************************************
    // 
    // With "Program Flow" or "Control Flow" ...  A.K.A. The messager throws exceptions and returns
    // true/false/null - I'm still confused as to what the right way to think about it even is.
    // 
    // It has something to do with **NOT** catching exceptions...
    // But it also has something to do with "Messager.checkErrors"
    // 
    // I really don't completely get what I'm doing at the moment with "Control-Flow"
    // 
    // ********************************************************************************************
    // ********************************************************************************************


    LJSMirror(
            // This is the Annotation, as a simple Java-String.  This is very useful for
            // Error-Printing with the Messager.  That's the only purpose of it

            final String annotationAsStr,

            // The parsed arguments to to the Annotation
            final List<? extends ExpressionTree> arguments,


            // The Signature of the Detail-Entity onto which this "@LinkJavaSource" Annotation
            // was placed.

            final String signature,

            // The set of all acceptable handles for a package
            final ReadOnlySet<String> allPkgLJSHandles,


            // This is a list of all of the LJS Files that were loaded as a result of the '.json'
            // Files list of External LJS Files AND ARE UN-PARSED.  The user has the ability to
            // ask that a file not be parsed.  The value here is that many external '.java' Files
            // are very short classes that contain only one method.  In such cases the external
            // HTML-Anchor element DOESN'T NEED A LINE-NUMBER AT ALL !  It just needs the
            // '.java.html' File-Name.
            // 
            // This is a list of such classes.

            final ReadOnlySet<String> unParsedLJSFilesList
        )
    {
        String  handle          = null;
        String  typeName        = null;
        Entity  entity          = null;
        String  name            = null;
        Byte    paramCount      = null;
        boolean notJustHandle   = false;

        ReadOnlyList<String> paramNames     = null;
        ReadOnlyList<String> paramTypesJOW  = null;

        for (int i = 0; i < arguments.size(); i++)
        {
            final ExpressionTree expr = arguments.get(i);

            if (! (expr instanceof AssignmentTree)) Messager.assertFail(
                "Annotation Placed:\n" +
                "    " + BCYAN + annotationAsStr + RESET + '\n' +
                "While parsing the Arguments / Elements of an LJSMirror Annotation, the " +
                "Oracle-Parser (com.sun.source.tree) returned an instance of `ExpressionTree` " +
                "that was not an instance of `AssignmentTree`.  This error should have been " +
                "caught by `javac` during the Compilation of this Source-File.",
                WHERE_AM_I
            );

            final AssignmentTree assignExpr = (AssignmentTree) expr;

            // Extracting the left-hand side (LHS) and right-hand side (RHS)
            ExpressionTree LHS = assignExpr.getVariable();
            ExpressionTree RHS = assignExpr.getExpression();

            final String lhsStr = LHS.toString();
            // final String rhsStr = RHS.toString().replace("\\'", "'");

            final String rhsStr = (RHS instanceof LiteralTree) 
                ? ((LiteralTree) RHS).getValue().toString()
                : RHS.toString();

            String temp;

            final Where_Am_I WHERE_AM_I = JDUAnnotations.LJSMirror;

            switch (lhsStr)
            {
                case "handle":

                    if (handle != null) HELPER.dupErrorAE
                        (annotationAsStr, handle, "handle", rhsStr, WHERE_AM_I);
                    else
                        handle = rhsStr;

                    break;


                case "typeName":

                    if (typeName != null) HELPER.dupErrorAE
                        (annotationAsStr, typeName, "typeName", rhsStr, WHERE_AM_I);
                    else
                        typeName = rhsStr;

                    notJustHandle = true;
                    break;


                case "entity":

                    if (entity != null) HELPER.dupErrorAE
                        (annotationAsStr, entity, "entity", rhsStr, WHERE_AM_I);
                    else 
                        entity = ecParser.valueOf(rhsStr, signature);

                    notJustHandle = true;
                    break;


                case "name":

                    if (name != null) HELPER.dupErrorAE
                        (annotationAsStr, name, "name", rhsStr, WHERE_AM_I);
                    else 
                        name = rhsStr;

                    notJustHandle = true;
                    break;


                case "paramCount":

                    if (paramCount != null) HELPER.dupErrorAE
                        (annotationAsStr, paramCount, "paramCount", rhsStr, WHERE_AM_I);

                    else if (! StringParse.isByte(rhsStr)) Messager.userErrorContinue(
                        "Annotation Placed:\n" +
                        "    " + BCYAN + annotationAsStr + RESET + '\n' +
                        "The value you have provided to element 'paramCount' is not a valid Byte:\n" +
                        "    [" + BRED + rhsStr + RESET + "]\n" +
                        MsgPrintTools.annotationProcessingError(),
                        WHERE_AM_I
                    );

                    else paramCount = Byte.parseByte(rhsStr);

                    notJustHandle = true;
                    break;


                case "paramNames":

                    if (paramNames != null) HELPER.dupErrorAE
                        (annotationAsStr, paramNames, "paramNames", rhsStr, WHERE_AM_I);
                    else
                        paramNames = extractStringArray(rhsStr);

                    notJustHandle = true;
                    break;


                case "paramTypesJOW":

                    if (paramTypesJOW != null) HELPER.dupErrorAE
                        (annotationAsStr, paramTypesJOW, "paramTypesJOW", rhsStr, WHERE_AM_I);
                    else
                        paramTypesJOW = extractStringArray(rhsStr);

                    notJustHandle = true;
                    break;


                default: Messager.userErrorContinue(
                    "While proessing a @LinkJavaSource Annotation, the following " +
                    "Annotation-Element Name was found:\n" +
                    "    [" + lhsStr + "]\n" +
                    "This is not a valid Annotation-Argument, and this error should have been " +
                    "caught by `javac` during its Compilation-Phase.  This is not one of " +
                    "@LinkJavaSource' Elements (sometimes called \"Arguements\")\n" +
                    "Valid Element-Names for this Annotation Include:\n" +
                    "    handle, typeName, entity, name, paramCount, paramNames " +
                    "and paramTypesJOW\n" +
                    "Have you disabled Annotation-Processing?",
                    WHERE_AM_I
                );
            }
        }

        // "entity" shall remain null if it wasn't passed a value
        // I used to do the following:
        // 
        // this.entity = (entity == null) ? Entity.METHOD : entity;

        // Assigning values to final fields
        this.annotationAsStr    = annotationAsStr;
        this.handle             = handle;
        this.typeName           = typeName;
        this.name               = name;
        this.entity             = entity;
        this.paramCount         = paramCount;
        this.paramNames         = paramNames;
        this.paramTypesJOW      = paramTypesJOW;

        // This is not an actual Annotation-Element, it is a 
        this.hrefOnlyNoLineNum = notJustHandle == false;

        LJSErrorCheck.check(this, unParsedLJSFilesList, allPkgLJSHandles, signature);
    }


    // ********************************************************************************************
    // ********************************************************************************************
    // Helpers
    // ********************************************************************************************
    // ********************************************************************************************


    // Helper method to extract string arrays from ExpressionTree
    private ReadOnlyList<String> extractStringArray(String rhsStr)
    {
        // The user may pass a String-Array of Length=1, and omit the Squiggly-Braces
        // If he has done so, there will not Squiggly-Braces!

        // if (rhsStr.charAt(0) != '{')
        //    return ReadOnlyList.of(StringParse.ifQuotesStripQuotes(rhsStr));

        // Assuming format: "fieldName={value1, value2, value3}"
        rhsStr = rhsStr.substring(1, rhsStr.length() - 1);

        String[] sArr = rhsStr.split(",");

        for (int i=0; i < sArr.length; i++)
            sArr[i] = StringParse.ifQuotesStripQuotes(sArr[i].trim());

        return ReadOnlyList.of(sArr);
    }


    // ********************************************************************************************
    // ********************************************************************************************
    // toString
    // ********************************************************************************************
    // ********************************************************************************************


    /** {@inheritDoc} */ @Override
    public String toString()
    {
        // public final String                 handle;
        // public final String                 typeName;
        // public final Entity                 entity;
        // public final String                 name;
        // public final Byte                   paramCount;
        // public final ReadOnlyList<String>   paramNames;
        // public final ReadOnlyList<String>   paramTypesJOW;
        // public final boolean                hrefOnlyNoLineNum;
        // 
        // 19 ==> Width of the Title Strings....  They are all 19 characters wide

        return 
            annotationAsStr + '\n' +
            "{\n" +
            "// Category: User Specifications for Hi-Liting and Linking onto Java-Doc Page\n" +
            "    entity:        " + HELPER.TOSTR(this.entity)               + '\n' +
            "    name:          " + HELPER.TOSTR(this.name, 19)             + '\n' +
            "    paramCount:    " + paramCount                              + '\n' +
            "    paramNames:    " + HELPER.TOSTR(this.paramNames, 19)       + '\n' +
            "    paramTypesJOW: " + HELPER.TOSTR(this.paramTypesJOW, 19)    + '\n' +
            '\n' +
            "// Category: Source-Code File and Class Specification\n" +
            "    handle:        " + HELPER.TOSTR(this.handle, 19)           + '\n' +
            "    typeName:      " + HELPER.TOSTR(this.typeName, 19)         + '\n' +
            '}';
    }
}