package Torello.Browser;

import Torello.Java.StringParse;

/**
 * Converts Chrome DevTools Protocol data objects and builders into readable diagnostic text.
 *
 * <BR /><BR />
 * This class provides the shared implementation used by {@link BaseType#toString()} and by
 * {@link AbstractBuilder#toString()}.  It walks the descriptor metadata associated with a CDP
 * data-carrier object or builder, retrieves each field or assigned value, and prints the result
 * using the compact type information defined by {@link CDPTypes}.
 * 
 * <BR /><BR />
 * The implementation is intentionally split across three small internal-support classes:
 *
 * <BR /><BR />
 * <UL CLASS=JDUL>
 * 
 * <LI><B><CODE>CDPToString</CODE></B> controls the overall formatting process.</LI>
 * 
 * <LI> <B><CODE>ParamRec</CODE></B> stores the current object, descriptor, indentation, padding,
 *      and value-retrieval function for one formatting pass.
 *      </LI>
 * 
 * <LI> <B><CODE>ValSwitch</CODE></B> performs the type-byte dispatch needed to print primitive
 *      values, strings, arrays, raw JSON values, and nested CDP data types.
 *      </LI>
 * </UL>
 *
 * <BR /><BR />
 * 💡 The important design point is that both {@code BaseType<?>} instances and
 * {@code AbstractBuilder<?>} instances can be printed through the same descriptor-driven pathway.
 * The only meaningful difference is how the value for each descriptor entry is retrieved.
 */
@Torello.JavaDoc.Annotations.JDHeaderBackgroundImg(EmbedTagFileID="INTERNAL_USE_JDHBI")
public class CDPToString
{
    private CDPToString() { }


    // ********************************************************************************************
    // ********************************************************************************************
    // Actual Entry Points
    // ********************************************************************************************
    // ********************************************************************************************


    // Called from class 'AbstractBuilder'
    static String toString(final AbstractBuilder<?> AB_THIS)
    { return toString(new ParamRec(AB_THIS)); }

    // Called from class 'BaseType'
    static String toString(final BaseType<?> BT_THIS)
    {
        // Only Marker Events have "empty" classes.  Such events will never be nested inside of 
        // another class.  This issue has already been checked in the surrounding code.

        return (BT_THIS.numFields == 0)
            ? BT_THIS.getClass().getName() + ": Marker-Event, w/ 0 Fields\n"
            : toString(new ParamRec(BT_THIS));
    }


    // ********************************************************************************************
    // ********************************************************************************************
    // "Main" Method
    // ********************************************************************************************
    // ********************************************************************************************


    // This is not private, because it is used inside 'ValSwitch'
    // It is used to recursively print BaseType<?> and BaseType<?>[]
    // Otherwise this would look much better if it were private.

    static String toString(final ParamRec rec)
    {
        for (int i=0; i < rec.NUM; i++)
        {
            final Object value;

            value = rec.getValue.apply(i);

            rec.sb
                .append(rec.INDENT)
                .append(StringParse.rightSpacePad(rec.descriptor.names.get(i), rec.NAME_PADDING));

            final byte typeByte = rec.descriptor.types.get(i);


            // After 2 hours of arguing with Chat-GPT, it wrote this to describe what it just spent
            // the afternoon doing.  Looks great if you ask me...
            //
            // IMPORTANT:
            //
            // Primitive/String/Number types can recover their printable type-name directly
            // from the CDPTypes lookup tables.
            //
            // HOWEVER:
            //
            // Complex nested CDP types (CDP_TYPE / CDP_TYPE_ARRAY_1D) do not store their
            // concrete Java class names inside the descriptor metadata itself.
            //
            // In those cases, the descriptor's package-private "getClass(...)" reflection
            // method is used to recover the underlying Java type.
            //
            // This allows null-values to still print meaningful type information such as:
            //
            //     RunTime.PropertyPreview[]
            //     Network.CookiePartitionKey
            //
            // rather than merely:
            //
            //     CDP_TYPE
            //     CDP_TYPE_ARRAY_1D
            //
            // NOTE:
            //
            // CommandDescriptor reflection is intentionally limited to locating the actual
            // Script-returning command method, NOT the zero-argument CommandBuilder factory
            // method generated for convenience.

            if (value != null)
                ValSwitch.print(rec, value, typeByte);

            else
            {
                final String cdpTypeStr = CDPTypes.types.get(typeByte);

                final String typeStr = (cdpTypeStr != null)
                    ? cdpTypeStr
                    : className(rec.descriptor.getClass(rec.descriptor.names.get(i), i));

                rec.sb.append(
                    "null (" + typeStr + ", " +
                    (rec.descriptor.optionals.get(i) ? "" : "not ") +
                    "declared optional)\n"
                );
            }
        }

        final String I = StringParse.nChars(' ', rec.CURRENT_INDENT - 4);

        return
            rec.printedName + ":\n" +
            I + "{\n" +
            rec.sb.toString() +
            I + "}\n";
    }


    // ********************************************************************************************
    // ********************************************************************************************
    // Static Helpers
    // ********************************************************************************************
    // ********************************************************************************************


    // This helper intentionally preserves nested-class '.' notation.
    //
    // Java reflection APIs often emit nested types using '$':
    // ➡️ RunTime$ObjectPreview
    //
    // whereas this utility converts the output into:
    // ➡️ RunTime.ObjectPreview
    //
    // which is substantially more readable in generated diagnostics.
    //
    // Array types are recursively normalized so that:
    // ➡️ RunTime.PropertyPreview[]
    //
    // is emitted instead of JVM-style array descriptors.

    static String className(final Class<?> c)
    {
        if (c.isArray()) return className(c.getComponentType()) + "[]";

        final String    canonical   = c.getCanonicalName();
        final Package   pkg         = c.getPackage();

        if (canonical == null)  throw new CDPToStringError("Canonical Name is null: " + c);
        if (pkg == null)        throw new CDPToStringError("Package is null: " + canonical);

        return canonical.substring(pkg.getName().length() + 1);
    }

    private static class CDPToStringError extends Error 
    {
        private static final long serialVersionUID = 1L;
        CDPToStringError(final String s) { super(s); }
    }

}