package Torello.Java.Build;

import Torello.Java.ReadOnly.ReadOnlyList;
import Torello.Java.StrCSV;

import Apache.CLI.Option;

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

import java.util.Objects;
import java.util.function.Function;


/**
 * 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=sor DATA-FILE-ID=CLI_GET_REFERENCE>
 * 
 * <BR /><BR />This record is how used to preserve the User's Command-Line input at a higher
 * level.  The switches that the user has entered are all stored inside this record - except the
 * switches that correspond to Auxiliary Menu-Options.
 * 
 * @see AuxiliaryOptRecord
 */
public class SelectedOptionsRecord
{
    // These public fields are all available immediately after the class CLI has begun processing
    // the User's Command-Line Switches.
    // 
    // Immediately, the class CLI knows the "MENU_CHOICE" he has selected, and can tell very 
    // quickly all of the Package Nick-Names that he has entered (if any).

    /**
     * This field contains the end User-Selected Command-Line Main-Menu Option/Choice (as a 
     * {@code java.lang.String}).
     * 
     * <BR /><BR />Some common examples of routinely passed CLI switches that are ultimately 
     * assigned to this field include:
     * 
     * <BR /><BR /><UL CLASS=JDUL>
     * <LI> {@code "-1"} - signifying that the {@code 'javac'} Compiler-Stage be run (a.k.a.
     *      "Please Compile my Files, or <B STYLE='color: red;'><I>some</I></B> of my files").
     *      <BR /><BR /></LI>
     * 
     * <LI> {@code "-cb1"} - requesting that the Composite-Step Option of a "Complete Build" be 
     *      executed.  All {@code '.java'} Source-Files will be Java-Doc'd, those {@code '.html'}
     *      Documentation-Pages will be ugraded, and then archived/tar'ed.  Afterwards, the 
     *      generted {@code '.jar'}-File will be placed on your Domain-Website's Storage-Bucket, as
     *      will all of your Documentation-Pages for your Source-Code.
     *      <BR /><BR /></LI>
     * 
     * <LI> {@code "-pb1"} - requesting that some subset of packages in your source need to be
     *      re-compiled, documented, and possibly synchronized to your Cloud Storage Space.
     *      <BR /><BR /></LI>
     * 
     * </UL>
     * 
     * <EMBED CLASS=external-html DATA-FILE-ID=CLI_PUBLIC_FIELD>
     */
    public final String MENU_CHOICE;

    /**
     * This {@link ReadOnlyList} will, after constructing an instance of this class, contain the
     * exact list of Java-Packages that have been included in this build.
     * 
     * <BR /><BR />Most Build-Options will "Build" all Java Packages provided to the {@link Config}
     * class' {@link Config#packageList} array.  However, there are a few Main Menu-Options that 
     * allow for specifying, explicity, which Java Packages are to be included.
     * 
     * <BR /><BR />This is another option whose primary use is for speeding up your interactive
     * "builds".  If documenting your pages is important to you, and re-building and re-publishing
     * your documentation to your Web-Domain's Storage-Space, then requesting that just a small
     * sub-set of your packages' {@code '.html'}-Files need to be udating can speed things up
     * tremendously.
     * 
     * <BR /><BR /><B CLASS=JDDescLabel>How it's Used:</B>
     * 
     * <BR />Usually, this list will be identical to the list contained in 
     * {@link BuildPackage}-Array {@link Config#packageList}.  The list of packages contained by
     * this list will be "abridged", if a list of Package Nick-Names were provided at the 
     * Command-Line.
     * 
     * <BR /><BR />Please review, at the top of this class, precisely which Main Menu-Options
     * allow for specifying a list of "Package Nick-Names."  It is for those precise Menu Choices
     * that this particular field will be somewhat shorter than the User-Provided array contained
     * within class {@link Config} Array-Field {@link Config#packageList}.
     * 
     * <BR /><BR /><B CLASS=JDDescLabel>Steps / Stages Affected:</B>
     * 
     * <BR /><BR /><UL CLASS=JDUL>
     * 
     * <LI> <B>{@link S01_JavaCompiler}</B> - This list is utilized to decide which
     *      Java-Packages actually need to be compiled by {@code 'javac'}.
     *      <BR /><BR /></LI>
     * 
     * <LI> <B>{@link S03_Upgrade}</B> - Employed to decide which Java-Doc {@code '.html'}-Files
     *      require upgrading, by the Java-Doc Upgrader.
     *      <BR /><BR /></LI>
     * 
     * <LI> <B>{@link S05_SyncJavaDoc}</B> - Used to decide which {@code '.html'}-Files must be
     *      re-copied to your Web-Domain's Storage-Bucket directories, so that your Java-Doc based
     *      Web-Site contains your latest changes.
     *      <BR /><BR /></LI>
     * 
     * </UL>
     * 
     * <BR /><BR />Note that many of the stages, (Stage-2, for instance) ignore completely the 
     * contents of this {@code ReadOnlyList}.  The original {@code 'javadoc'} program will always
     * rebuild your entire Java-Doc Site, because it is the source of many, many URL-Anchor
     * ({@code '<A HREF=...>'}) links.
     * 
     * <BR /><BR />Furthermore your Archive-Files (your {@code '.jar'} and {@code '.tar'}) files
     * will never "leave out" any {@code '.class'}-Files or Source-Code.
     * 
     * <BR /><BR />The Steps within this Build-Tool that allow for Package Nick-Name's to be passed
     * at the Command-Line are only their for quickly, and efficiently, upgrading your Java-Doc 
     * Web-Site so that you may <B STYLE='color: red'><I>quickly</I></B> inspect how your latest
     * round of changes actually look on the web.
     * 
     * <BR /><BR /><BR /><B CLASS=JDDescLabel>How it's Populated:</B>
     * 
     * <BR /><DIV CLASS=SNIP>{@code
     * final ArrayList<String> l = new ArrayList<>();
     * 
     * if (nickNamesProvided)
     *      for (String pkgNickName : nickNames) l.add(pkgNickName);
     * 
     * if (EXTRA_PACKAGE_NICKNAMES)
     *      for (String pkgNickName : extraneousArgs) l.add(pkgNickName);
     * 
     * this.userProvidedNickNames = nickNamesProvided
     *      ? new ReadOnlyArrayList<String>(l)
     *      : null;
     * 
     * this.userSpecifiedPackages = nickNamesProvided
     *      ? BuildPackage.nickNameArgVPackages(packageList, this.userProvidedNickNames)
     *      : null;
     * }</DIV>
     * 
     * <EMBED CLASS=external-html DATA-FILE-ID=CLI_PUBLIC_FIELD>
     * 
     * @see Config#packageList
     * @see #userProvidedNickNames
     */
    public final ReadOnlyList<BuildPackage> userSpecifiedPackages;

    /**
     * Please see the documentation for the field {@link #userSpecifiedPackages}, since this field
     * contains nearly identical information.
     * 
     * <BR /><BR />This field is populated by extracting the actual User-Provided Nick-Name from
     * each of the {@link BuildPackage} instances that are stored within the
     * {@link #userSpecifiedPackages} list.
     * 
     * <EMBED CLASS=external-html DATA-FILE-ID=CLI_PUBLIC_FIELD>
     * @see Config#packageList
     * @see #userProvidedNickNames
     */
    public final ReadOnlyList<String> userProvidedNickNames;

    /**
     * The Complete-List of all Options / Switches entered at the Command-Line.
     */
    public final ReadOnlyList<Option> optList;

    SelectedOptionsRecord(
            final String                        MENU_CHOICE,
            final ReadOnlyList<String>          userProvidedNickNames,
            final ReadOnlyList<BuildPackage>    userSpecifiedPackages,
            final ReadOnlyList<Option>          optList
        )
    {
        this.MENU_CHOICE            = MENU_CHOICE;
        this.userProvidedNickNames  = userProvidedNickNames;
        this.userSpecifiedPackages  = userSpecifiedPackages;
        this.optList                = optList;
    }


    // ********************************************************************************************
    // ********************************************************************************************
    // 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()
    {
        final String upnn = (this.userProvidedNickNames != null)
            ? this.userProvidedNickNames.toString()
            : "null, meaning none-provided";

        final Function<Option, String> PRINTER = (Option opt) ->
            "\n\t" + opt.toString();

        return 
            BCYAN + "this.MENU_CHOICE:            " + RESET + this.MENU_CHOICE + "\n" +
            BCYAN + "this.userProvidedNickNames:  " + RESET + upnn + "\n" +
            BCYAN + "this.userSpecifiedPackages:  " + RESET + "[See Above List]\n\n" +
            BCYAN + "this.optList: " + RESET +
                "**Apache.CLI.Option instances, toString()-invocation**" +
                StrCSV.toCSV(this.optList, PRINTER, true, null) + '\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 SelectedOptionRecord}
     * 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 SelectedOptionsRecord)) return false;
        SelectedOptionsRecord other = (SelectedOptionsRecord) o;

        return
                Objects.equals(this.MENU_CHOICE, other.MENU_CHOICE)
            &&  Objects.equals(this.userProvidedNickNames, other.userProvidedNickNames)
            &&  Objects.equals(this.userSpecifiedPackages, other.userSpecifiedPackages)
            &&  Objects.equals(this.optList, other.optList);
    }

    /**
     * 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.MENU_CHOICE.hashCode() + this.userProvidedNickNames.hashCode(); }
}