package Torello.Java.Additional;

import Torello.JavaDoc.JDHeaderBackgroundImg;
import Torello.Java.Verbosity;

// Used for the JavaDoc '@see' tag, a few lines directly-below
import Torello.HTML.Tools.Images.ImageScraper;

/**
 * Another Logging-Helper class.  This interface builds on the {@link AppendableSafe} class, and
 * in this case it meaans that the internal {@code Appendable} that is wrapped by this one is an
 * instance of {@link AppendableSafe} - <I>rather than the Standard-Java
 * {@code java.lang.Appendable} interface</I>.
 * 
 * <BR /><BR />The purpose of the {@link AppendableSafe} class is merely to prevent Java's
 * Checked-Exception {@code 'IOException'}, and replace it with any number of unchecked 
 * {@code Throwable} options.  The purpose of this class is merely to add several convenience
 * fields ({@link #hasLog} and {@link#level}) so that in the course of writing output-log code, a
 * programmer is not bogged-down with 'Verbose Log Code' (Logging code that is, itself, extremely
 * verbose-looking).
 * 
 * @see ImageScraper
 * @see AppendableSafe
 */
@JDHeaderBackgroundImg(EmbedTagFileID={"APPENDABLE_EXTENSION", "APPENDABLE_LOG_JDHBI"})
public class AppendableLog implements Appendable
{
    // ********************************************************************************************
    // ********************************************************************************************
    // Fields
    // ********************************************************************************************
    // ********************************************************************************************


    /** Four space-characters. */
    public static final String I4 = "    ";

    /** Eight space-characters. */
    public static final String I8 = I4 + I4;

    /** Twelve space-characters. */
    public static final String I12 = I8 + I4;

    /** Sixteen space-characters. */
    public static final String I16 = I8 + I8;

    /**
     * The actual log, itself.
     * 
     * <BR /><BR />This field may be passed and assigned null by the constructor.  The user should
     * be aware to take some care if null log's are allowed in your code.  This just means that 
     * there are circumstances where logging is to be "turned off".  In such cases, make sure to
     * write code that chcks whether the log is null before printing to it.  (Make sure to avoid 
     * throwing {@code NullPointerException})
     * 
     * <BR /><BR />This is an instance of {@link AppendableSafe} because the actual class
     * {@code java.lang.Appendable} has methods all of which throw {@code IOException}.  The
     * {@link AppendableSafe} class wraps those method calls and blocks the unchecked
     * {@code IOException's}.
     * 
     * @see AppendableSafe
     */
    public final AppendableSafe log;

    /**
     * Simple way for the user to identify whether or not a null {@code 'appendable'} parameter was
     * passed to this class Constructor.  If null was passed to {@link #log}, then this 
     * {@code boolean} will be false.
     */
    public final boolean hasLog;

    /** This is nothing more than the enum {@link Verbosity} field {@link Verbosity#level}. */
    public final int level;


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


    /**
     * Construct an instance of this class.  The {@code 'appendable'} parameter, if non-null, is
     * immediately wrapped into an {@link AppendableSafe} instance, and configured to throw 
     * {@link AppendableError} rather than {@code IOException} when / if the internal method throws
     * any {@code IOException's}.
     * 
     * @param appendable This may be any instance of {@code java.lang.Appendable}.
     * 
     * @param verbosity An instance of the {@link Verbosity} enum.  If parameter
     * {@code 'appendable'} is null, then this paramter may also be null.  However if
     * {@code 'appendable'} is non-null, then this may not be null either - or an exception shall
     * throw.
     * 
     * @throws NullPointerException If parameter {@code 'appendable'} is non-null, but parameter
     * {@code 'verbosity'} is null, then a {@code NullPointerException} will throw.
     */
    public AppendableLog(Appendable appendable, Verbosity verbosity)
    {
        if (appendable == null)
        {
            this.log    = null;
            this.hasLog = false;
            this.level  = 0;
        }

        else
        {
            this.log    = new AppendableSafe(appendable, AppendableSafe.USE_APPENDABLE_ERROR);
            this.hasLog = true;
            this.level  = verbosity.level;  // throws NPE
        }
    }

    /**
     * Construct an instance of this class.  Since there are several ways to configure the internal
     * {@link AppendableSafe} instance, this constructor allows a user to simply pass an already
     * built instance of {@code AppendableSafe} as a parameter.
     * 
     * @param appendableSafe This may be any instance of {@link AppendableSafe}.  The primary
     * purpose of this class is to shunt the {@code IOException} that is thrown by
     * {@code java.lang.Appendable} methods, and either suppress them, or re-wrap them into an
     * unchecked-{@code Throwable}.
     * 
     * <BR /><BR />Being able to leave off the {@code throws IOException} when writing log
     * code makes the process much easier.
     * 
     * @param verbosity An instance of the {@link Verbosity} enum.  If parameter
     * {@code 'appendableSafe'} is null, then this paramter may also be null.  However if
     * {@code 'appendableSafe'} is non-null, then this may not be null either - or an exception
     * shall throw.
     * 
     * @throws NullPointerException If parameter {@code 'appendableSafe'} is non-null, but
     * parameter {@code 'verbosity'} is null, then a {@code NullPointerException} will throw.
     */
    public AppendableLog(AppendableSafe appendableSafe, Verbosity verbosity)
    {
        if (appendableSafe == null)
        {
            this.log    = null;
            this.hasLog = false;
            this.level  = 0;
        }

        else
        {
            this.log    = appendableSafe;
            this.hasLog = true;
            this.level  = verbosity.level;  // throws NPE
        }
    }


    // ********************************************************************************************
    // ********************************************************************************************
    // java.lang.Appendable Methods
    // ********************************************************************************************
    // ********************************************************************************************


    /**
     * Appends the specified character to this {@code Appendable}.
     * 
     * <BR /><BR /><SPAN CLASS=CopiedJDK>Description copied from class:
     * {@code java.lang.Appendable}, <B>JDK 1.8</B></SPAN>
     * 
     * @param c The character to append
     * @return A reference to this {@code Appendable}.
     * 
     * @throws NullPointerException If the {@code AppendableSafe} instance field ({@link #log}) was
     * passed null during construction of {@code 'this'} instance.
     */
    public AppendableSafe append(char c)
    { return this.log.append(c); }

    /**
     * Appends the specified character sequence to this {@code Appendable}.
     * 
     * <BR /><BR />Depending on which class implements the character sequence {@code 'csq'}, the
     * entire sequence may not be appended.  For instance, if {@code 'csq'} is a
     * {@code 'CharBuffer'} the subsequence to append is defined by the buffer's position and limit.
     * 
     * <BR /><BR /><SPAN CLASS=CopiedJDK>Description copied from class:
     * {@code java.lang.Appendable}, <B>JDK 1.8</B></SPAN>
     * 
     * @param csq The character sequence to append. If csq is null, then the four characters "null"
     * are appended to this {@code Appendable}.
     * 
     * @return A reference to this {@code Appendable}.
     * 
     * @throws NullPointerException If the {@code AppendableSafe} instance field ({@link #log}) was
     * passed null during construction of {@code 'this'} instance.
     */
    public AppendableSafe append(CharSequence csq)
    { return this.log.append(csq); }

    /**
     * Appends a subsequence of the specified character sequence to this {@code Appendable}.
     * 
     * <BR /><BR />An invocation of this method of the form {@code out.append(csq, start, end)}
     * when {@code 'csq'} is not null, behaves in exactly the same way as the invocation:
     * 
     * <DIV CLASS=LOC>{@code
     * out.append(csq.subSequence(start, end)) 
     * }</DIV>
     * 
     * <BR /><BR /><SPAN CLASS=CopiedJDK>Description copied from class:
     * {@code java.lang.Appendable}, <B>JDK 1.8</B></SPAN>
     * 
     * @param csq The character sequence from which a subsequence will be appended. If csq is null,
     * then the four characters "null" are appended to this {@code Appendable}.
     * 
     * @param start The index of the first character in the subsequence
     * @param end The index of the character following the last character in the subsequence
     * 
     * @return A reference to this {@code Appendable}.
     * 
     * @throws NullPointerException If the {@code AppendableSafe} instance field ({@link #log}) was
     * passed null during construction of {@code 'this'} instance.
     */
    public AppendableSafe append(CharSequence csq, int start, int end)
    { return this.log.append(csq, start, end); }


    // ********************************************************************************************
    // ********************************************************************************************
    // More Appendable Methods
    // ********************************************************************************************
    // ********************************************************************************************


    /**
     * Appends four character spaces of indentation, and then appends {@code String}-parameter
     * {@code's'}.
     * 
     * @return A reference to this {@code Appendable}.
     * 
     * @throws NullPointerException If the {@code AppendableSafe} instance field ({@link #log}) was
     * passed null during construction of {@code 'this'} instance.
     */
    public AppendableSafe appendI4(String s)
    { return this.log.append(I4).append(s); }

    /**
     * Appends eight character spaces of indentation, and then appends {@code String}-parameter
     * {@code's'}.
     * 
     * @return A reference to this {@code Appendable}.
     * 
     * @throws NullPointerException If the {@code AppendableSafe} instance field ({@link #log}) was
     * passed null during construction of {@code 'this'} instance.
     */
    public AppendableSafe appendI8(String s)
    { return this.log.append(I8).append(s); }

    /**
     * Appends twelve character spaces of indentation, and then appends {@code String}-parameter
     * {@code's'}.
     * 
     * @return A reference to this {@code Appendable}.
     * 
     * @throws NullPointerException If the {@code AppendableSafe} instance field ({@link #log}) was
     * passed null during construction of {@code 'this'} instance.
     */
    public AppendableSafe appendI12(String s)
    { return this.log.append(I12).append(s); }

    /**
     * Appends sixteen character spaces of indentation, and then appends {@code String}-parameter
     * {@code's'}.
     * 
     * @return A reference to this {@code Appendable}.
     * 
     * @throws NullPointerException If the {@code AppendableSafe} instance field ({@link #log}) was
     * passed null during construction of {@code 'this'} instance.
     */
    public AppendableSafe appendI16(String s)
    { return this.log.append(I16).append(s); }


    // ********************************************************************************************
    // ********************************************************************************************
    // Boolean-Test Methods
    // ********************************************************************************************
    // ********************************************************************************************


    /**
     * Quick check that can be used to test whether or not to print to a log.  The purpose of an
     * instance of {@link Verbosity} is that logging information is only printed to an output log
     * if the user has requested a certain level of verbosity.
     * 
     * <BR /><BR />This method will return {@code TRUE} if the user has requested logging, and
     * this instance' internal {@link #level} field is equal to parameter {@code 'level'}.
     * 
     * @param level An integer that should correspond to the enum {@link Verbosity} internal field
     * {@link Verbosity#level}.
     * 
     * @return {@code TRUE} if -
     * 
     * <BR /><BR /><UL CLASS=JDUL>
     * <LI><B>{@link #hasLog}</B> is also {@code TRUE}</LI>
     * <LI><B>{@link #level}</B> equals value passed to parameter {@code 'level'}</LI>
     * </UL>
     * 
     * <BR />Returns {@code FALSE} otherwise
     */
    public boolean levelEQ(int level)
    {
        if (hasLog) return (this.level == level);
        return false;
    }

    /**
     * Quick check that can be used to test whether or not to print to a log.  The purpose of an
     * instance of {@link Verbosity} is that logging information is only printed to an output log
     * if the user has requested a certain level of verbosity.
     * 
     * <BR /><BR />This method will return {@code TRUE} if the user has requested logging, and
     * this instance' internal {@link #level} field is greater than or equal to parameter
     * {@code 'level'}.
     * 
     * @param level An integer that should correspond to the enum {@link Verbosity} internal field
     * {@link Verbosity#level}.
     * 
     * @return {@code TRUE} if -
     * 
     * <BR /><BR /><UL CLASS=JDUL>
     * 
     * <LI> Field <B>{@link #hasLog}</B> is also {@code TRUE}</LI>
     * 
     * <LI> Field <B>{@link #level}</B> is greater than or equal to value passed to parameter
     *      {@code 'level'}
     *      </LI>
     * </UL>
     * 
     * <BR />Returns {@code FALSE} otherwise
     */
    public boolean levelGTEQ(int level)
    {
        if (hasLog) return (this.level >= level);
        return false;
    }
}