package Torello.JDUInternal.Annotations.EntityAnnotations.Mirror;

import static Torello.Java.C.BCYAN;
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.JDUInternal.Messager.Messager;
import Torello.JDUInternal.Messager.Where.Where_Am_I;
import Torello.JDUInternal.Messager.Where.JDUAnnotations;

import Torello.JDUInternal.Annotations.HELPER;

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;

// EXPORTS:
// 
//     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:
// 
// * Torello.JavaDoc.LinkJavaSource
//      For the actual annotation definition.
//      This is the actual @interface for the @LinkJavaSource Annotation
// 
// * 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
// 
// * Torello.JDUInternal.Annotations.EntityAnnotations.Mirror.LJSMirror
//      The Data-Contents of Annotation that has been placed by the User on the Entity
//      (Entity: Method, Field, Constructor, Enum-Constant, Annotation-Element)
// 
// * Torello.JDUInternal.Annotations.EntityAnnotations.Processor.LinkJSourceProcessor
//      The Annotation-Processor that is invoked by 'javac' when compiling a class that uses the
//      @LinkJavaSource Annotation.  

public class LJSMirror
{
    private static final Where_Am_I WHERE_AM_I = JDUAnnotations.LJSMirror;


    // ********************************************************************************************
    // ********************************************************************************************
    // Fields
    // ********************************************************************************************
    // ********************************************************************************************


    public final String                 annotationAsStr;
    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;


    // ********************************************************************************************
    // ********************************************************************************************
    // Constructor
    // ********************************************************************************************
    // ********************************************************************************************


    // 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 **ALWAUS** 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      = -1;
        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.assertFailOracleParser(
                "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.",
                signature,
                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();

            switch (lhsStr)
            {
                case "handle":
                    handle = StringParse.ifQuotesStripQuotes(rhsStr);
                    break;

                case "typeName":
                    notJustHandle = true;
                    typeName = StringParse.ifQuotesStripQuotes(rhsStr);
                    break;

                case "entity":
                    notJustHandle = true;
                    entity = Entity.valueOf(rhsStr);
                    break;

                case "name":
                    notJustHandle = true;
                    name = StringParse.ifQuotesStripQuotes(rhsStr);
                    break;

                case "paramCount":
                    notJustHandle = true;
                    paramCount = Byte.parseByte(rhsStr);
                    if (paramCount == -1) LJSErrorCheck.passedMinusOne(annotationAsStr);
                    break;

                case "paramNames":
                    notJustHandle = true;
                    paramNames = extractStringArray(rhsStr);
                    break;

                case "paramTypesJOW":
                    notJustHandle = true;
                    paramTypesJOW = extractStringArray(rhsStr);
                    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);
    }


    // ********************************************************************************************
    // ********************************************************************************************
    // 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
    // ********************************************************************************************
    // ********************************************************************************************


    // Chat-GPT Generated.  It's a lot of fun to play with it, actually.
    public String toString()
    {
        return 
            annotationAsStr + ":\n" +
            '\n' +

            "// Category: User Specifications for Hi-Liting and Linking onto Java-Doc Page\n" +
            "    entity:        " + HELPER.TOSTR(entity)        + '\n' +
            "    name:          " + HELPER.TOSTR(name)          + '\n' +
            "    paramCount:    " + paramCount                  + '\n' +
            "    paramNames:    " + HELPER.TOSTR(paramNames)    + '\n' +
            "    paramTypesJOW: " + HELPER.TOSTR(paramTypesJOW) + '\n' +
            '\n' +

            "// Category: Source-Code File and Class Specification\n" +
            "    handle:        " + HELPER.TOSTR(handle)       + '\n' +
            "    typeName:      " + HELPER.TOSTR(typeName)     + '\n';
    }
}