package Torello.JavaDoc.Messager;

import Torello.Java.StrIndent;
import Torello.JavaDoc.Declaration;
import Torello.JavaDoc.ReflHTML;
import Torello.Java.C;

import static Torello.Java.C.RESET;
import static Torello.Java.C.BWHITE;
import static Torello.Java.C.RED_BKGND;


import java.util.Vector;

// A replacement for <CODE>System&#46;out, System&#46;err</CODE> and even the StorageWriter
// class used to send error messages to the terminal about upgrade progress.

/**
 * The Messager class is the top-level interface for emitting structured messages, warnings, and
 * assertion failures to the user terminal. It exposes a static API (e.g.,
 * {@code Messager.userError(...)}) that can be called from anywhere in the application without
 * requiring an explicit instance.
 * 
 * <EMBED CLASS='external-html' DATA-FILE-ID=MSGR_THREAD_LOCAL>
 * <EMBED CLASS='external-html' DATA-FILE-ID=MSGR_PARAM_TABLE>
 */
public class Messager
{
    /**
     * When {@code TRUE}, requests that the stack trace be printed to terminl output for any
     * Assertion-Failure Error-Message which contains an Exception-Throw
     */
    public static boolean DEFAULT_SHOW_STACK_TRACE_ON_ASSERT_FAIL = true;


    // ********************************************************************************************
    // ********************************************************************************************
    // Scoped-Values / ThreadLocal-Instance & Constructor
    // ********************************************************************************************
    // ********************************************************************************************


    private static final java.lang.ThreadLocal<Messager> tlInstance =
        new java.lang.ThreadLocal<>();

    /**
     * Initializes the {@code ThreadLocal<Messager>} instance for the current thread.
     * 
     * <BR /><BR />
     * This method must be called exactly once per thread, before any of the static
     * {@link Messager} printing methods (such as {@code userError},
     * {@code assertionFailure}, etc.) are invoked. It constructs and wires together the internal
     * helper classes {@link PrintRecord}, {@link PrintHeading}, and {@link PrintMessage}, and
     * binds the resulting {@code Messager} object to the current thread using
     * {@code ThreadLocal.set()}.
     *
     * <BR /><BR />
     * This design avoids the need to explicitly pass around {@code Messager} instances
     * across the application and enables safe, isolated message formatting per thread.
     * This is particularly useful for tools that may one day process multiple source files
     * or build artifacts in parallel (e.g., future parallelization of the JDU tool).
     *
     * <BR /><BR />
     * This method must not be called more than once on the same thread. Doing so will result
     * in an {@code InternalError}, as re-initialization would overwrite the existing
     * {@code Messager} instance and compromise internal state.
     * 
     * @param verbosityLevel The verbosity level for message output (must be between 0 and 3
     * inclusive).  Higher levels enable more verbose diagnostic output.
     *
     * @param logAppendable The {@code Appendable} to which log output should be written.  May be
     * {@code null} if no log file output is needed.  If so, Output-Text is not saved to disk.
     *
     * @throws InternalError if this method is called more than once per thread and different
     * assigned values to {@code 'verbosityLevel'} or {@code 'logAppendable'} are provided on the
     * separate invocations.
     * 
     * <BR /><BR />This {@code Error} will also throw if the {@code verbosityLevel} is out of range
     */
    public static void initializeThreadLocalInstance
        (final int verbosityLevel, final Appendable logAppendable)
    {
        Messager m = tlInstance.get();


        // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
        // Newer Addition: This method may be invoked multiple times
        // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
        // 
        // In order to facilitate calling some of the JDU's Features before the Upgrader has 
        // started running - which in the partiular case that forced this new addition was 
        // handling an Error by the File-HiLiter inside the "MoreHiliting" Class - the Messager 
        // has to be initialized before the Upgrader even starts it's primary "upgrade()" Method.
        // 
        // The default solution is to allow this method to be called as many times as are needed,
        // with the minor caveat that if the input values change in any way shape or form, then
        // an InternalError shall throw.

        if (m != null)
        {
            final boolean eqV = (m.printRecord.verbosityLevel == verbosityLevel);
            final boolean eqL = m.printRecord.checkEqualsLogAppendable(logAppendable);

            if (eqV && eqL) return;

            final String vStr = eqV
                ? ""
                :   "The input Verbosity-Level [" + verbosityLevel + "], does not equal the " +
                    "previously assigned Verbosity-Level [" + m.printRecord.verbosityLevel + "]\n";

            final String lStr = eqL
                ? ""
                :   "The input Log-Appendable is a different instance / reference Object than " +
                    "the previously assigned Log-Appendable.\n";

            throw new InternalError(
                "Messager.initializeThreadLocalInstance(int, Appendable) has been called " +
                "multiple times.  On this invocation:\n" + vStr + lStr
            );
        }

        if ((verbosityLevel < 0) || (verbosityLevel > 3)) throw new InternalError(
            "verbosityLevel=" + verbosityLevel + ", " +
            "but it must be between 0 and 3."
        );

        final PrintRecord   printRecord     = new PrintRecord(verbosityLevel, logAppendable);
        final PrintHeading  printHeading    = new PrintHeading(printRecord);
        final PrintMessage  printMessage    = new PrintMessage(printRecord, printHeading);
        final Messager      messager        = new Messager(printRecord, printMessage);

        tlInstance.set(messager);
    }


    // ********************************************************************************************
    // ********************************************************************************************
    // Constructor & Fields
    // ********************************************************************************************
    // ********************************************************************************************


    private final PrintRecord   printRecord;
    private final PrintMessage  printMessage;


    private Messager(final PrintRecord printRecord, final PrintMessage printMessage)
    {
        this.printRecord    = printRecord;
        this.printMessage   = printMessage;
    }


    // ********************************************************************************************
    // ********************************************************************************************
    // Simple print / println ... and one "warning" Printer-Method
    // ********************************************************************************************
    // ********************************************************************************************


    public static void print(final String s)
    {
        final Messager m = tlInstance.get();
        if (m.printRecord.verbosityLevel >= 2) m.printRecord.screenWriterSW.print(s);
    }

    public static void println(final String s)
    {
        final Messager m = tlInstance.get();
        if (m.printRecord.verbosityLevel >= 2) m.printRecord.screenWriterSW.println(s);
    }

    public static void println()
    {
        final Messager m = tlInstance.get();
        if (m.printRecord.verbosityLevel >= 2) m.printRecord.screenWriterSW.println();
    }

    public static void printQuiet(final String s)
    {
        final Messager m = tlInstance.get();
        if (m.printRecord.verbosityLevel == 1) m.printRecord.screenWriterSW.print(s);
    }

    public static void printSilent(final boolean dotOrNewLine)
    {
        final Messager m = tlInstance.get();

        if (m.printRecord.verbosityLevel == 0)
            m.printRecord.screenWriterSW.print(dotOrNewLine ? '.' : '\n');
    }

    public static void ifVerboseAppendVerbose()
    {
        final Messager m = tlInstance.get();

        if (m.printRecord.verbosityLevel == 3)
            m.printRecord.screenWriterSW.print(MsgVerbose.getAndClear());
    }

    public static void warning(final String message, final Where_Am_I WHERE_AM_I)
    {
        final Messager m = tlInstance.get();

        m.printMessage.WARNING(message, WHERE_AM_I);
        m.printRecord.writeSBToScreen();
    }


    // ********************************************************************************************
    // ********************************************************************************************
    // Fatal-Assert: Throws to Stop Program-Execution Immediatley
    // ********************************************************************************************
    // ********************************************************************************************


    public static Error assertFail(final String message, final Where_Am_I WHERE_AM_I)
    {
        final Messager m = tlInstance.get();

        m.printMessage.ERROR(
            message,
            null,   // signature
            true,   // FATAL
            WHERE_AM_I
        );

        m.printRecord.writeSBToScreen();
        throw new AssertFail();
    }

    public static Error assertFail
        (final String message, final String signature, final Where_Am_I WHERE_AM_I)
    {
        final Messager m = tlInstance.get();

        m.printMessage.ERROR(
            message,
            signature,
            true, // FATAL
            WHERE_AM_I
        );

        m.printRecord.writeSBToScreen();
        throw new AssertFail();
    }

    public static Error assertFail
        (final Throwable t, final String message, final Where_Am_I WHERE_AM_I)
    {
        final Messager m = tlInstance.get();

        m.printMessage.ERROR(
            t,
            message,
            null,   // signature
            true,   // FATAL
            DEFAULT_SHOW_STACK_TRACE_ON_ASSERT_FAIL,
            WHERE_AM_I
        );

        m.printRecord.writeSBToScreen();
        throw new AssertFail();
    }

    public static Error assertFail(
            final Throwable     t,
            final String        message,
            final String        signature,
            final Where_Am_I    WHERE_AM_I
        )
    {
        final Messager m = tlInstance.get();

        m.printMessage.ERROR(
            t,
            message,
            signature,
            true,   // FATAL
            DEFAULT_SHOW_STACK_TRACE_ON_ASSERT_FAIL,
            WHERE_AM_I
        );

        m.printRecord.writeSBToScreen();
        throw new AssertFail();
    }


    // ********************************************************************************************
    // ********************************************************************************************
    // Non-Fatal Assert: Error, but it doesn't need to stop immediately
    // ********************************************************************************************
    // ********************************************************************************************


    public static void assertFailContinue(final String message, final Where_Am_I WHERE_AM_I)
    {
        final Messager m = tlInstance.get();

        m.printMessage.ERROR(
            message,
            null,   // signature
            false,  // NON-FATAL
            WHERE_AM_I
        );

        m.printRecord.writeSBToScreen();
    }

    public static void assertFailContinue
        (final Throwable t, final String message, final Where_Am_I WHERE_AM_I)
    {
        final Messager m = tlInstance.get();

        m.printMessage.ERROR(
            t,
            message,
            null,   // signature
            false,  // NON-FATAL
            false,  // Don't Show Stack-Trace
            WHERE_AM_I
        );

        m.printRecord.writeSBToScreen();
    }


    // ********************************************************************************************
    // ********************************************************************************************
    // Fatal-User-Error: Throws to Stop Program-Execution Immediatley
    // ********************************************************************************************
    // ********************************************************************************************


    public static Error userErrorHalt(final String message, final Where_Am_I WHERE_AM_I)
    {
        final Messager m = tlInstance.get();

        m.printMessage.ERROR(
            message,
            null,       // signature    
            true,       // FATAL
            WHERE_AM_I
        );

        m.printRecord.writeSBToScreen();
        throw new MessagerGeneratedError();
    }

    public static Error userErrorHalt
        (final Throwable t, final String message, final Where_Am_I WHERE_AM_I)
    {
        final Messager m = tlInstance.get();

        m.printMessage.ERROR(
            t,          // Exception that was thrown
            message,    // THE MESSAGE
            null,       // signature    
            true,       // FATAL
            true,       // Show Stack-Trace
            WHERE_AM_I
        );

        m.printRecord.writeSBToScreen();
        throw new MessagerGeneratedError();
    }


    // ********************************************************************************************
    // ********************************************************************************************
    // User-Error: Program-Flow Execution Continues
    // ********************************************************************************************
    // ********************************************************************************************


    public static void userErrorContinue(final String message, final Where_Am_I WHERE_AM_I)
    {
        final Messager m = tlInstance.get();

        m.printMessage.ERROR(
            message,
            null,   // signature
            false,  // NON-FATAL
            WHERE_AM_I
        );

        m.printRecord.writeSBToScreen();
    }

    public static void userErrorContinue
        (final String message, final String signature, final Where_Am_I WHERE_AM_I)
    {
        final Messager m = tlInstance.get();

        m.printMessage.ERROR(
            message,
            signature,
            false, // NON-FATAL
            WHERE_AM_I
        );

        m.printRecord.writeSBToScreen();
    }

    public static void userErrorContinue
        (final Throwable t, final String message, final Where_Am_I WHERE_AM_I)
    {
        final Messager m = tlInstance.get();

        m.printMessage.ERROR(
            t,
            message,
            null,   // signature
            false,  // NON-FATAL
            false,  // Don't Show Stack-Trace
            WHERE_AM_I
        );

        m.printRecord.writeSBToScreen();
    }

    public static void userErrorContinueST
        (final Throwable t, final String message, final Where_Am_I WHERE_AM_I)
    {
        final Messager m = tlInstance.get();

        m.printMessage.ERROR(
            t,
            message,
            null,   // signature
            false,  // NON-FATAL
            true,   // SHOW STACK TRACE
            WHERE_AM_I
        );

        m.printRecord.writeSBToScreen();
    }


    // ********************************************************************************************
    // ********************************************************************************************
    // The Old Class "MsgControl"
    // ********************************************************************************************
    // ********************************************************************************************


    public static void setCurrentFileName(final String fName, final String fNameKind)
    {
        final Messager m = tlInstance.get();
        m.printRecord.setCurrentFileName(fName, fNameKind);
    }

    public static void setTopDescriptionSection()
    {
        final Messager m = tlInstance.get();
        m.printRecord.setTopDescriptionSection();
    }

    public static void setDeclaration(final Declaration declaration)
    {
        final Messager m = tlInstance.get();
        m.printRecord.setDeclaration(declaration);
    }

    public static boolean hadErrors()
    {
        final Messager m = tlInstance.get();
        return m.printRecord.hadErrors();
    }

    public static void ifLogCheckPointLog()
    {
        final Messager m = tlInstance.get();
        if (! m.printRecord.hasLogAppendable) return;
        m.printRecord.checkPointLog();
    }

}