package Torello.Java.Build;

import Apache.CLI.Option;
import Torello.Java.ReadOnly.ReadOnlyList;

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

/**
 * This class contains an internally used {@code boolean}-Flag field corresponding to each of the
 * Auxiliary Command-Line Options / Switches available by this Build-Tool.
 * 
 * <!-- Contains the black-banner declaring this is a CLI-group internally used class -->
 * <EMBED CLASS='external-html' DATA-FILE-ID=CLI_INTERNAL_USE>
 * 
 * <!-- Explains how to retrieve an instance of this class, and provides an example -->
 * <EMBED CLASS='external-html' DATA-FIELDNAME=aor DATA-FILE-ID=CLI_GET_REFERENCE>
 * 
 * <BR /><BR />This record is used to help convert Command-Line Switches into
 * {@code boolean}-Constants.  These {@code final-boolean} fields are used inside:
 * 
 * <BR /><BR /><UL CLASS-JDUL>
 *      <LI>Inside class {@link CLI}'s Constructor</LI>
 *      <LI>The class {@link BuilderRecord}'s constructor</LI>
 *      <LI>Inside of the 8 various stages of this Build-Tool</LI>
 * </UL>
 * 
 * <BR /><BR />This Record does help "keep clear" which Auxiliary-Switches are offered.  There is
 * also an Error-Checking class for this record.  The class ({@link ErrorCheckAuxOpts}) checks each
 * of the field in this class corresponds to <B STYLE='color: red;'><I>EXACTLY ONE</I></B> of the
 * available <B>{@code "Auxiliary Options"}</B> that may be entered into the Command-Line or
 * "Terminal Window".
 * 
 * <BR /><BR />This class will do nothing more than copy these switches into a Read-Only Record.
 * Since the new JDK-21 Records are, indeed, "ReadOnly" - this class will possibly be converted
 * into a JDK-Record (instead of class), but not today.  Right now, JDK-11 has its benefits too.
 * I am stuck in Java 11, and I'm not exactly sure when I will be able to transition.  Certainly
 * this year, though.
 * 
 * @see SelectedOptionsRecord
 */
public class AuxiliaryOptRecord 
{
    /**
     * To-Do: Create a detailed explanation of this sick little bugger.
     * 
     * <EMBED CLASS=external-html DATA-FILE-ID=CLI_PUBLIC_FIELD>
     * @see BuildPackage#QUICKER_BUILD_SKIP
     */
    public final boolean NO_QUICK_BUILD_SWITCH;

    /**
     * One of the Primary Build-Goals for this Build-Package is to generate a standard Java
     * {@code '.jar'}-File from your Source-Code.  If you feel you have changed something in your
     * code, and need to use the classes that are contained within your previously constructed
     * {@code '.jar'}-File in your class-path, there is an Auxiliary-Menu Option for this.
     * 
     * <BR /><BR /><B CLASS=JDDescLabel>How it's Used:</B>
     * 
     * <BR />If the user has passed the {@code '-JCP'} Parameter at the Command-Line, then this
     * {@code boolean}-Field will be assigned {@code TRUE}, and the Stage-01 {@code 'javac'}
     * invocation will include whatever {@code '.jar'}-File in the Class-Path when it executes /
     * runs {@code 'javac'} on your {@code '.java'} Source-Code Files.
     * 
     * <EMBED CLASS=external-html DATA-FILE-ID=CLI_PUBLIC_FIELD>
     */
    public final boolean INCLUDE_JAR_IN_CP_SWITCH;

    /**
     * One of the really powerful advantages to using this Build-Tool, is that re-compiling and
     * updating your doc-files to your web-site can all be done with one single Command-Line
     * invocation.  This means your development process moves along nearly as fast the JDK's
     * {@code 'javac'}-Command.
     * 
     * <BR /><BR />In all honesty, the slowest part of the Java-HTML Build Process is copying
     * 10,000 Java-Doc {@code '.html'} Files to the appropriate Google Storage-Bucket.  If you 
     * have a Web-Address that is used for making your Source-Documentation Publicly-Visibly where
     * it is not mission-critical to first remove all of the older documentation pages that are 
     * already present inside the Storage-Bucket's directories - <I>you may pass the Command-Line
     * switch {@code '-SRG'} to your build, and the "Remove the Old Files" procedure will be
     * skipped</I>.
     * 
     * <BR /><BR />In Java-HTML, compiling, documenting and synchronizing all of the generated
     * JavaDoc-Files to the Web can take upwards of 2.5 minutes.  Passing the {@code '-SRG'}
     * switch can shave off up to 30 seconds of Command-Line Wait-Time.
     * 
     * <BR /><BR /><B CLASS=JDDescLabel>How it's Used:</B>
     * 
     * <BR />This field will be assigned {@code TRUE} precisely when the {@code '-SRG'} 
     * Command-Line Switch has been passed to the <B>{@code String[] argv}</B>
     * {@code String[]}-Array Parameter.
     * 
     * <BR /><BR />When this Configuration-Field has been assigned {@code FALSE}, it will be
     * comletel ignored, and the standard routine of deleting the old {@code 'html'}-Files from 
     * your Web-Domain's {@code Storage-Buckets} (your "original"), will be removed before the
     * new {@code '.html'}-Files are copied.
     * 
     * <BR /><BR />However, when this field is assigned {@code TRUE}, the Stage-5 Build-Logic
     * will skip the removal of old {@code '.html'}-Files from your Bucket-Directories.
     * 
     * <BR /><BR />As your {@code '.jar'}-File grows in size, this can save you several seconds
     * of wating and staring at your Command-Line / Terminal Text-Output (waiting for you Build
     * to finish, so you can see what the doc's look like).
     * 
     * <EMBED CLASS=external-html DATA-FILE-ID=CLI_PUBLIC_FIELD>
     */
    public final boolean SKIP_REMOVE_GCS_FILES_SWITCH;

    /**
     * This Build-Package's Command-Line Interface, as explained at the top of this {@code '.html'}
     * Page, will accept the flag <B>{@code '-TXL'}</B>.
     * 
     * <BR /><BR />The class {@code Config} has a User-Assignable {@code Boolean}-Field called, 
     * simply, {@link Config#USE_XLINT_SWITCH}.  When this Build-Tool is configured such that this 
     * Configuration-Field is assigned {@code TRUE}, the Stage-1 Compilation {@code 'javac'} Stage
     * will be executed with the included switch {@code '-Xlint:all,-processing'}.
     * 
     * <BR /><BR />This can often help spot bugs which, according the JDK are not errors, just
     * warnings (for instance), by halting the build when they occur.  If you have a preference,
     * then simply assigned {@code TRUE} or {@code FALSE} to the {@link Config} instance that is
     * passed to class {@link BuilderRecord}.
     * 
     * <BR /><BR />Now, in the event that this {@code 'javac'} switch is forcing your Build too
     * fail, and you would like compile with such warnings anyway, you may pass the switch 
     * {@code '-TXL'} at the Command-Line, at it will <B STYLE='color: red;'>'toggle'</B> whatever
     * assigned {@code Boolean}-Value was provided to class {@code Config} in your {@code '.java'}
     * Source-File.
     * 
     * <BR /><BR />Note that this also means that if you have this Compiler-Flag turned off by
     * default, it may be temporarily "activated" at the Command-Line by passing the switch
     * {@code '-TXL'} when you invoke class {@link RunBuild}.
     * 
     * <BR /><BR /><B CLASS=JDDescLabel>How it's Used:</B>
     * 
     * <BR />The value of this particular {@code Boolean}-Field will be {@code TRUE} when the
     * switch was identified by the Apache-CLI Options-Processing code.  It will be assigned 
     * {@code FALSE} (in this class, {@link CLI}, constructor) - when the switch is not present.
     * 
     * <BR /><BR />The Build Stage-1 {@code 'javac'} Build-Step will decide whether or not to
     * employ the {@code '-Xlint:all,-processing'} switch based on the value assigned to
     * <B STYLE='color: red'>BOTH</B> the {@link Config#USE_XLINT_SWITCH}
     * <B STYLE='color: red'>AND</B> the value assigned this field, as well.
     * 
     * <BR /><BR />Again, when this field is {@code TRUE}, it just requests that the value stored
     * to {@link Config#USE_XLINT_SWITCH} be <B STYLE='color: red;'>toggled</B> before being
     * interpreted by the Stage 01 Build-Step ({@code 'javac'}).
     * 
     * <EMBED CLASS=external-html DATA-FILE-ID=CLI_PUBLIC_FIELD>
     * @see Config#USE_XLINT_SWITCH
     */
    public final boolean OVERRIDE_TOGGLE_USE_XLINT_SWITCH;

    /**
     * This Build-Package's Command-Line Interface, as explained at the top of this {@code '.html'}
     * Page, will accept the flag <B>{@code '-TXD'}</B>.
     * 
     * <BR /><BR />This field is nearly identical to the final {@code Boolean}-Field, above,
     * {@link #OVERRIDE_TOGGLE_USE_XLINT_SWITCH}.  This field is used to
     * <B STYLE='color: red;'>'toggle'</B> the User-Provided setting, passed by to class
     * {@link Config}, assigned to the field {@link Config#USE_XDIAGS_SWITCH}.
     * 
     * <BR /><BR />In the exact same fashion as {@link Config#USE_XLINT_SWITCH}, when the field
     * {@link Config#USE_XDIAGS_SWITCH} is {@code TRUE}, it means that the Stage-1 Build-Logic
     * should include the Command-Line switch {@code '-Xdiags:verbose'} when executing
     * {@code 'javac'}.  Quite a bit of useful information can, occasionally, be made available
     * by the {@code 'javac'} command (by passing this switch to {@code 'javac'} at its
     * Command-Line).
     * 
     * <BR /><BR />However, when it is spitting out warnings, it also means your compilation
     * stage will be prematurely halted.
     * 
     * <BR /><BR /><B CLASS=JDDescLabel>How it's Used:</B>
     * 
     * <BR />The value of this particular {@code Boolean}-Field will be {@code TRUE} when the
     * switch was identified by the Apache-CLI Options-Processing code.  It will be assigned 
     * {@code FALSE} (in this class, {@link CLI}, constructor) - when the switch is not present.
     * 
     * <BR /><BR />The Build Stage-1 {@code 'javac'} Build-Step will decide whether or not to
     * employ the {@code '-Xdiags:verbose'} switch based on the value assigned to
     * <B STYLE='color: red'>BOTH</B> the {@link Config#USE_XDIAGS_SWITCH}
     * <B STYLE='color: red'>AND</B> the value assigned this field, as well.
     * 
     * <BR /><BR />Again, when this field is {@code TRUE}, it just requests that the value stored
     * to {@link Config#USE_XDIAGS_SWITCH} be <B STYLE='color: red;'>toggled</B> before being
     * interpreted by the Stage 01 Build-Step ({@code 'javac'}).
     * 
     * <EMBED CLASS=external-html DATA-FILE-ID=CLI_PUBLIC_FIELD>
     * @see Config#USE_XDIAGS_SWITCH
     */
    public final boolean OVERRIDE_TOGGLE_USE_XDIAGS_SWITCH;

    /**
     * Adding a new Java-Package to a <B STYLE='color: red;'>{@code CI/CD: Continuous-Integraton /
     * Continuous-Delivery}</B> Build-System can be somewhat un-nerving.  If you would like to add
     * a new Package - but occasionally want to leave it out of the Publicly-Visible
     * Synchronization-Stages, then mark your packages (in class <B>{@link BuildPackage}</B>) with
     * the <B>{@link BuildPackage#EARLY_DEVELOPMENT}</B> Flag.
     * 
     * <BR /><BR />Using the Command-Line Switch <B>{@code "-IED"}</B>, you will be able to include
     * or exclude such appropriately flagged Java-Packages as you see fit.
     * 
     * <BR /><BR /><B CLASS=JDDescLabel>How it's Used:</B>
     * 
     * <BR />The value assigned to this field will be {@code TRUE} precisely when the Build Switch
     * {@code "-IED"} has been passed at the Command-Line.
     * 
     * <BR /><BR />When this field has been assigned {@code FALSE}, it will be ignored, completely
     * by the Build-Logic.  However, when it is assigned {@code TRUE}, any of your Java-Packages
     * that have been configured with the {@link  BuildPackage#EARLY_DEVELOPMENT}-Flag will be
     * 'elided' (to use a new, JDK-21+ term) or 'eliminated' completely from your Build-Process.
     * 
     * <EMBED CLASS=external-html DATA-FILE-ID=CLI_PUBLIC_FIELD>
     * @see BuildPackage#EARLY_DEVELOPMENT
     */
    public final boolean INCLUDE_EARLY_DEV_PACKAGES_SWITCH;

    /**
     * For Menu-Option #4, "Run Archive-Stage - generate {@code '.tar'} and {@code '.jar'} Files",
     * the user amy provided a Command-Line Switch {@code "-JFO"}.  This switch allows a user to
     * request that only a Java {@code '.jar'}-File be generated, and that the Java-Doc
     * {@code 'tar'}-File and the Project Source-Code Archive {@code '.tar'}-File be skipped.
     * 
     * <BR /><BR />This Auxiliary-Switch can only be applied if the Main-Menu Choice that has been
     * provided is Command-Line Option {@code "-4"}, or the Composite-Stage Command-Line Option for
     * Stages {@code "-1"} through {@code "-4"} has been entered.
     * 
     * <BR /><BR />If neither of these two Menu-Options were entered at the termainal /
     * Command-Line Interface, then this Build-Tool will print the Help-Menu and report that an
     * error has occurred.
     * 
     * <EMBED CLASS=external-html DATA-FILE-ID=CLI_PUBLIC_FIELD>
     */
    public final boolean JAR_FILE_ONLY_SWITCH;

    /**
     * This option may be specified in combination with Main-Menu Option #1 (The Java-Compiler).
     * This asks that before any of the Source-Files for any of the Packages-to-be-compiled are
     * actually sent to 'javac', their respective '.class'-Files should, first, be removed and
     * deleted from disk.
     * 
     * <BR /><BR />This Auxiliary-Switch may only be used in combination with Main-Menu Option
     * "-1".  If used with any of the other Primary or Composite Stage Build-Requests, the CLI
     * Processor will flag the input as an error.
     */
    public final boolean WIPE_CLASS_FILES_FIRST;


    AuxiliaryOptRecord(ReadOnlyList<Option> optList)
    {
        // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
        // Fill in this class' "Extra Switch Fields" (These are the non-main-menu Switches)
        // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
        //
        // All of these variables are declared, even though they are largely just exact copies of
        // the public fields declared at the top of this class - BECAUSE THOSE FIELDS ARE ALL
        // DECLARED 'final' - Meaning they may only be assigned once in this giant constructor that
        // I have written.
        // 
        // Declaring them 'final' means they can also be declared 'public', and the end user can
        // play with them to his heart's content, wihthout having the ability to screw anything up
        // either!

        boolean
            NO_QUICK_BUILD_SWITCH               = false,
            INCLUDE_JAR_IN_CP_SWITCH            = false,
            SKIP_REMOVE_GCS_FILES_SWITCH        = false,
            OVERRIDE_TOGGLE_USE_XLINT_SWITCH    = false,
            OVERRIDE_TOGGLE_USE_XDIAGS_SWITCH   = false,
            INCLUDE_EARLY_DEV_PACKAGES_SWITCH   = false,
            JAR_FILE_ONLY_SWITCH                = false,
            WIPE_CLASS_FILES_FIRST              = false;

        for (Option opt : optList) switch (opt.getOpt())
        {
            case "NQB"  : NO_QUICK_BUILD_SWITCH                 = true; break;
            case "JCP"  : INCLUDE_JAR_IN_CP_SWITCH              = true; break;
            case "SRG"  : SKIP_REMOVE_GCS_FILES_SWITCH          = true; break;
            case "TXL"  : OVERRIDE_TOGGLE_USE_XLINT_SWITCH      = true; break;
            case "TXD"  : OVERRIDE_TOGGLE_USE_XDIAGS_SWITCH     = true; break;
            case "IEDP" : INCLUDE_EARLY_DEV_PACKAGES_SWITCH     = true; break;
            case "JFO"  : JAR_FILE_ONLY_SWITCH                  = true; break;
            case "WCFF" : WIPE_CLASS_FILES_FIRST                = true; break;
            // default  : continue;
        }

        this.NO_QUICK_BUILD_SWITCH              = NO_QUICK_BUILD_SWITCH;
        this.INCLUDE_JAR_IN_CP_SWITCH           = INCLUDE_JAR_IN_CP_SWITCH;
        this.SKIP_REMOVE_GCS_FILES_SWITCH       = SKIP_REMOVE_GCS_FILES_SWITCH;
        this.OVERRIDE_TOGGLE_USE_XLINT_SWITCH   = OVERRIDE_TOGGLE_USE_XLINT_SWITCH;
        this.OVERRIDE_TOGGLE_USE_XDIAGS_SWITCH  = OVERRIDE_TOGGLE_USE_XDIAGS_SWITCH;
        this.INCLUDE_EARLY_DEV_PACKAGES_SWITCH  = INCLUDE_EARLY_DEV_PACKAGES_SWITCH;
        this.JAR_FILE_ONLY_SWITCH               = JAR_FILE_ONLY_SWITCH;
        this.WIPE_CLASS_FILES_FIRST             = WIPE_CLASS_FILES_FIRST;
    }


    // ********************************************************************************************
    // ********************************************************************************************
    // java.lang.Object (Would JDK-21+ Record do this for me by automatic?)
    // ********************************************************************************************
    // ********************************************************************************************


    /**
     * Converts {@code 'this'} instance to a {@code java.lang.String}
     * @return This class represented as a {@code String}.
     */
    public String toString()
    {
        return 
            BCYAN + "this.NO_QUICK_BUILD_SWITCH                 " + RESET +
                NO_QUICK_BUILD_SWITCH + "\n" +

            BCYAN + "this.INCLUDE_JAR_IN_CP_SWITCH              " + RESET +
                INCLUDE_JAR_IN_CP_SWITCH + "\n" +

            BCYAN + "this.SKIP_REMOVE_GCS_FILES_SWITCH:         " + RESET +
                SKIP_REMOVE_GCS_FILES_SWITCH + "\n" +

            BCYAN + "this.OVERRIDE_TOGGLE_USE_XLINT_SWITCH:     " + RESET +
                OVERRIDE_TOGGLE_USE_XLINT_SWITCH + "\n" +

            BCYAN + "this.OVERRIDE_TOGGLE_USE_XDIAGS_SWITCH:    " + RESET +
                OVERRIDE_TOGGLE_USE_XDIAGS_SWITCH + "\n" +

            BCYAN + "this.INCLUDE_EARLY_DEV_PACKAGES_SWITCH:    " + RESET +
                INCLUDE_EARLY_DEV_PACKAGES_SWITCH + "\n" +

            BCYAN + "this.JAR_FILE_ONLY_SWITCH:                 " + RESET +
                JAR_FILE_ONLY_SWITCH + "\n" +

            BCYAN + "this.WIPE_CLASS_FILES_FIRST:               " + RESET +
                WIPE_CLASS_FILES_FIRST + "\n";
    }

    /**
     * Check's for equality between {@code 'this'} instance, and any other instance of
     * {@code java.lang.Object}
     * 
     * @param o Any Java Object-Reference.  Only an instance of class {@code AuxiliaryOptRecord}
     * will generate a return-value of {@code TRUE}, and particularly only one whose fields are all
     * equal to the corresponding fields in {@code 'this'} instance.
     * 
     * @return {@code TRUE} if and only if {@code 'o'} and {@code 'this'} are equal, as explained
     * above.
     */
    public boolean equals(Object o)
    {
        if (! (o instanceof AuxiliaryOptRecord)) return false;

        AuxiliaryOptRecord other = (AuxiliaryOptRecord) o;

        return 
                (this.NO_QUICK_BUILD_SWITCH ==
                    other.NO_QUICK_BUILD_SWITCH)
    
            &&  (this.INCLUDE_JAR_IN_CP_SWITCH ==
                    other.INCLUDE_JAR_IN_CP_SWITCH)

            &&  (this.SKIP_REMOVE_GCS_FILES_SWITCH ==
                    other.SKIP_REMOVE_GCS_FILES_SWITCH)

            &&  (this.OVERRIDE_TOGGLE_USE_XLINT_SWITCH ==
                    other.OVERRIDE_TOGGLE_USE_XLINT_SWITCH)

            &&  (this.OVERRIDE_TOGGLE_USE_XDIAGS_SWITCH ==
                    other.OVERRIDE_TOGGLE_USE_XDIAGS_SWITCH)

            &&  (this.INCLUDE_EARLY_DEV_PACKAGES_SWITCH ==
                    other.INCLUDE_EARLY_DEV_PACKAGES_SWITCH)

            &&  (this.JAR_FILE_ONLY_SWITCH ==
                    other.JAR_FILE_ONLY_SWITCH)

            &&  (this.WIPE_CLASS_FILES_FIRST ==
                    other.WIPE_CLASS_FILES_FIRST);
    }

    /**
     * Generates a Hash-Code for use with Standard-Java {@code Hashtable's} etc...
     * 
     * @return A (somewhat) unique Hash-Code, to be used for placing an instance of this 
     * class into any variant of Hash-Table.
     */
    public int hashCode()
    { 
        return 
            (this.NO_QUICK_BUILD_SWITCH                 ? 1             : 0) +
            (this.INCLUDE_JAR_IN_CP_SWITCH              ? 10            : 0) +
            (this.SKIP_REMOVE_GCS_FILES_SWITCH          ? 100           : 0) +
            (this.OVERRIDE_TOGGLE_USE_XLINT_SWITCH      ? 1_000         : 0) +
            (this.OVERRIDE_TOGGLE_USE_XDIAGS_SWITCH     ? 10_000        : 0) +
            (this.INCLUDE_EARLY_DEV_PACKAGES_SWITCH     ? 100_000       : 0) +
            (this.JAR_FILE_ONLY_SWITCH                  ? 1_000_000     : 0) +
            (this.WIPE_CLASS_FILES_FIRST                ? 10_000_000    : 0);
    }
}