package Torello.Java.Build;

import Apache.CLI.*;

import static Torello.Java.C.*;

import Torello.Java.UnreachableError;
import Torello.Java.StrCmpr;

import Torello.Java.ReadOnly.ReadOnlyList;
import Torello.Java.ReadOnly.ReadOnlyArrayList;

import java.util.ArrayList;
import java.util.List;
import java.util.stream.Stream;
import java.io.File;

/**
 * This data class is generated by parsing the Command-Line Input to a Builder Invocation, and it
 * contains the settings that were extrapolated by the Apache CLI Parser.  When a {@link Builder}
 * instance is created, its constructor requires that a Java {@code `String[] argv`} array be
 * included as a Constructor-Parameter.  The provided {@code String[]}-Array is used to build an
 * instance of this class.
 * 
 * <BR /><BR />The data contained as fields of this class is all declared {@code public} and also
 * {@code ReadOnly} or {@code final}.  The instance generated from the Command-Line Input (CLI)
 * parser is available as a {@code public} and {@code final} field of the {@link Builder} instance
 * field {@link Builder#cli Torello.Java.Build.Builder.cli};
 * 
 * <BR /><BR />This class does not offer any public constructors, nor any public methods.  It is 
 * automatically built by class {@code Builder}, which has package-level access to this class' sole
 * constructor.
 * 
 * <EMBED CLASS='external-html' DATA-FILE-ID=CLI_SWITCHES>
 */
public class CLI
{
    // ********************************************************************************************
    // ********************************************************************************************
    // Fields
    // ********************************************************************************************
    // ********************************************************************************************


    public final String     MENU_CHOICE;
    public final boolean    INCLUDE_JAR_IN_CP;
    public final boolean    SKIP_REMOVE_GCS_FILES;
    public final boolean    JAR_ONLY;
    public final boolean    INCLUDE_EARLY_DEV_PACKAGES;
    public final boolean    toReleaseOrDeveloper;
    public final boolean    QUICKER_BUILD;
    public final boolean    OVERRIDE_TOGGLE_USE_XLINT_SWITCH;
    public final boolean    OVERRIDE_TOGGLE_USE_XDIAGS_SWITCH;
    public final String     GCS_DIR;

    // Option #1 and #21.  Note, it was decided both of these shall be 'null' instead of
    // empty-lists (when they would otherwise be empty-lists)

    public final ReadOnlyList<BuildPackage>    userSpecifiedPackages;
    public final ReadOnlyList<String>          userProvidedNickNames;


    // ********************************************************************************************
    // ********************************************************************************************
    // Main-Menu Options-Group
    // ********************************************************************************************
    // ********************************************************************************************


    // This generates an "OptionGroup" that contains all of the choices for the Main-Menu
    // Exactly one of these options must be chosen by the user.
    //
    // If zero **OR** more than one is chosen, then the CLI-Constructor will throw an exception and
    // print an error message
    //
    // The Options Include:
    //  * 8 Individual Build-Steps
    //  * 3 Complete-Build Composite-Steps (These perform steps 1 through 7/8)
    //  * 2 Developer-Build Composite-Steps (These perform a subset of steps 1 - 8)

    private static OptionGroup mainOptions()
    {
        // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
        // Primary Build-Step Options
        // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***

        final Option javac = Option
            .builder        ("1")
            .required       (false)
            .desc           ("Build Stage 1: Java-Compiler")
            .longOpt        ("javac")
            .hasArgs        ()
            .optionalArg    (true)
            .valueSeparator (' ')
            .argName        ("PackageNickNames")
            .build();

        final Option javaDoc = Option
            .builder    ("2")
            .required   (false)
            .desc       ("Build Stage 2: Standard 'javadoc' Tool")
            .longOpt    ("javadoc")
            .hasArg     (false)
            .build();

        final Option jdu = Option
            .builder    ("3")
            .required   (false)
            .desc       ("Build Stage 3: Torello Java-Doc Upgrader")
            .longOpt    ("jdu")
            .hasArg     (false)
            .build();

        final Option tarJar = Option
            .builder        ("4")
            .required       (false)
            .desc           ("Build Stage 4, Archive-Files")
            .longOpt        ("tarjar")
            .optionalArg    (true)  // "JARONLY"
            .valueSeparator (' ')
            .argName        ("JARONLY")
            .build();


        // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
        // Sync-Step Options
        // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***

        final Option syncJavaDoc = Option
            .builder    ("5")
            .required   (false)
            .desc       ("Build Stage 5: Sync 'javadoc/'")
            .longOpt    ("syncJavaDoc")
            .hasArg     (false)
            .build();

        final Option syncTarJar = Option
            .builder    ("6")
            .required   (false)
            .desc       ("Build Stage 6: Sync Tar & Jar")
            .longOpt    ("syncTarJar")
            .hasArg     (false)
            .build();

        final Option syncLogs = Option
            .builder    ("7")
            .required   (false)
            .desc       ("Build Stage 7: Sync Log-Files")
            .longOpt    ("syncLogs")
            .hasArg     (false)
            .build();

        final Option setMaxAge = Option
            .builder    ("8")
            .required   (false)
            .desc       ("Build Stage 8: Set Max-Age Browser-Cache")
            .longOpt    ("setMaxAge")
            .hasArg     (false)
            .build();


        // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
        // Composite-Step / Complete-Build Options
        // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***

        final Option buildRel = Option
            .builder    ("cb1")
            .required   (false)
            .desc       ("Complete Build: STEPS 2 to 7. Sync-To: GCP-Release")
            .longOpt    ("buildRel")
            .hasArg     (false)
            .build();

        final Option buildDevSMA = Option
            .builder    ("cb2")
            .required   (false)
            .desc       ("Complete Build: STEPS 2 to 8. Sync-To: GCP-Developer")
            .longOpt    ("buildDevSMA")
            .hasArg     (false)
            .build();

        final Option buildDev = Option
            .builder    ("cb3")
            .required   (false)
            .desc       ("Complete Build: STEPS 2 to 7. Sync-To: GCP-Developer")
            .longOpt    ("buildDev")
            .hasArg     (false)
            .build();


        // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
        // Partial Debugging / Developer Build
        // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***

        final Option partialAll = Option
            .builder    ("pb1")
            .required   (false)
            .desc       ("Partial-Debuging Build: STEPS 2 & 3. (Doc Only)")
            .longOpt    ("partialAll")
            .hasArg     (false)
            .build();

        final Option partialSome = Option
            .builder        ("pb2")
            .required       (false)
            .desc           ("Partial-Debuging Build: STEPS 2, 3, 5, and 8. To: GCP-Developer")
            .longOpt        ("partialSome")
            .hasArgs        ()
            .optionalArg    (true)
            .valueSeparator (' ')
            .argName        ("PackageNickNames")
            .build();


        // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
        // Run Links Checker
        // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***

        final Option linksCheck = Option
            .builder    ("LC")
            .required   (false)
            .desc       ("Links Checker Build")
            .longOpt    ("linksCheck")
            .hasArg     (false)
            .build();


        // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
        // INSERT ALL INTO THE "OptionGroup" ... And return that instance
        // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***

        final OptionGroup group = new OptionGroup();

        group.setRequired(true);
        group
            // Primary Build-Step Options
            .addOption(javac)
            .addOption(javaDoc)
            .addOption(jdu)
            .addOption(tarJar)

            // Sync-Step Options
            .addOption(syncJavaDoc)
            .addOption(syncTarJar)
            .addOption(syncLogs)
            .addOption(setMaxAge)

            // Composite-Step / Complete-Build Options
            .addOption(buildRel)
            .addOption(buildDevSMA)
            .addOption(buildDev)

            // Partial Debugging / Developer Build
            .addOption(partialAll)
            .addOption(partialSome)

            // Run Links Checker
            .addOption(linksCheck);

        return group;
    }


    // ********************************************************************************************
    // ********************************************************************************************
    // Other / Extra Menu Options
    // ********************************************************************************************
    // ********************************************************************************************


    // There are also three little "Extra Switches" that the user can provide / select.
    // These three are just for convenience - making my life easier.

    private static final String descriptionNQB =    
        "Prevent a Quick Build during Partial-Build's";

    private static final String descriptionJCP =
        "Include the '.jar' File in the Class-Path";

    private static final String descriptionSRG =
        "Skip the removal-step of all Java-Doc GCS Files, when synchronizing.";

    private static final String descriptionTXL =
        "Toggle whatever the default setting is for applying -Xlint:all";

    private static final String descriptionTXD =
        "Toggle whatever the default setting is for applying -Xdiags:verbose";

    private static final String descriptionIEDP =
        "Include Packages still Under Early Development in the Build";


    private static List<Option> otherNonGroupOptionNiceties()
    {
        final Option noQuickBuild = Option
            .builder    ("NQB")
            .required   (false)
            .desc       (descriptionNQB)
            .longOpt    ("noQuickBuild")
            .hasArg     (false)
            .build();

        final Option putJarInCP = Option
            .builder    ("JCP")
            .required   (false)
            .desc       (descriptionJCP)
            .longOpt    ("putJarInCP")
            .hasArg     (false)
            .build();

        final Option skipRemoveGCSFiles = Option
            .builder    ("SRG")
            .required   (false)
            .desc       (descriptionSRG)
            .longOpt    ("skipRemoveGCSFiles")
            .hasArg     (false)
            .build();

        final Option overrideToggleXlintSwitch = Option
            .builder    ("TXL")
            .required   (false)
            .desc       (descriptionTXL)
            .longOpt    ("toggleDefaultXlint")
            .hasArg     (false)
            .build();

        final Option overrideToggleXdiagsSwitch = Option
            .builder    ("TXD")
            .required   (false)
            .desc       (descriptionTXD)
            .longOpt    ("toggleDefaultXdiags")
            .hasArg     (false)
            .build();

        final Option includeEarlyDevPkgsSwitch = Option
            .builder    ("IEDP")
            .required   (false)
            .desc       (descriptionIEDP)
            .longOpt    ("includeEarlyDev")
            .hasArg     (false)
            .build();

        return List.of(
            noQuickBuild,
            putJarInCP,
            skipRemoveGCSFiles,
            overrideToggleXlintSwitch,
            overrideToggleXdiagsSwitch,
            includeEarlyDevPkgsSwitch
        );
    }


    // ********************************************************************************************
    // ********************************************************************************************
    // Process the Command-Line Arguments
    // ********************************************************************************************
    // ********************************************************************************************


    CLI(
            String          GCS_DIR_DEV,
            String          GCS_DIR_RELEASE,
            BuildPackage[]  packageList,
            String[]        argv
        )
    {
        // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
        // Fill up Apache.CLI.Options (Get "Option" instances from the above two static methods)
        // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***

        final Options options = new Options();

        // The "OptionGroup" instance contains the complete list of Menu-Options offered by this
        // Build Package.  Exactly **ONE** of these Options should be selected by the user.

        final OptionGroup optGroup = mainOptions();

        // Add the main / top-level Command-Line Arguments
        options.addOptionGroup(optGroup);

        // Add the little extras.
        for (Option o : otherNonGroupOptionNiceties()) options.addOption(o);


        // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
        // Parse 'argv' using 'options' - Do some error checking
        // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***

        final CommandLine commandLine;

        try
        {
            commandLine = DefaultParser
                .builder()
                .setAllowPartialMatching(false)
                .setStripLeadingAndTrailingQuotes(true)
                .build()
                .parse(options, argv, false /* stopAtNonOption */);
        }

        // This happens when the user hasn't provided at least one of the "OptionGroup" switches
        // All of the "Option" instances inside the "OptionGroup" are the **COMPLETE** list of 
        // Menu-Options offered by this build.  Exactly 1 must be provided at the command line, or
        // else this exception throws.  If so, just print an error message and exit.

        catch (MissingOptionException moe)
            { throw printMenuHelp(options, moe); }

        // I haven't been through all of Apache's list of other possible error messages.  If there
        // is one, print the Help-Menu, and the exception's message and exit.

        catch (ParseException pe)
            { throw printMenuHelp(options, pe); }


        // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
        // Retrieve the Selected-Option's name, instance-reference, & number-as-byte
        // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***

        final String selectedOptName = optGroup.getSelected();

        Option tempOpt = null;
        for (Option o : optGroup.getOptions()) if (o.getOpt().equals(selectedOptName))
        {
            tempOpt = o;
            break;
        }

        // It just looks better / smarter when variables that aren't going to change are actuallly
        // declared final

        final Option selectedOpt = tempOpt;

        // The argv-option parsing mechanism should already have thrown an exception if the user
        // failed to choose any of the provided options.

        if (selectedOpt == null) throw new UnreachableError();

        this.MENU_CHOICE = selectedOptName;


        // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
        // More Error-Checking - This part can only be accomplished after filling in MENU_CHOICE
        // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
        //
        // There are only 2 menu-options that accept a list of package nick-names:
        //
        // "javac"  (Option #1) Allows you to compile only the packages listed, if these names
        //          are included.
        //
        // "pb2"    (Partion-Build #2) Also allows the option of only Syncing-To-GCS the packages
        //          listed

        final boolean pkgNickNamesPossible =
            this.MENU_CHOICE.equals("1") || this.MENU_CHOICE.equals("pb2");

        // I simply cannot get Apache.CLI to allow for an Option that accepts ZERO, ONE or MANY
        // arguments.  The possibilities with Apache.CLI seem to be either "ZERO or ONE" (an
        // optional argument) **OR** "ONE-or-MORE" (multiple, but-not-zero).  Therefore, I sort of
        // have to rely on this "hack-y" thing where I check the "extra non-recognized" switches
        // to allow for the case of ZERO, ONE or MANY arguments to Options "-1" and "-pb2"

        final String[] extraneousArgs = commandLine.getArgs();

        // I can never tell (anywhere, when I'm coding!) if it is going to be null, or a
        // zero-length-array.  You eventually just get used to typing this...
        // I'm also getting used to typing 'final' everywhere when I know a variable just
        // isn't going to change.

        final boolean EXTRA_PACKAGE_NICKNAMES =
            ((extraneousArgs != null) && (extraneousArgs.length > 0));

        if (EXTRA_PACKAGE_NICKNAMES)
        {
            if (! pkgNickNamesPossible) throw printMenuHelp(options, extraneousArgs);

            // These two lists, if non-empty, are going to cause an error-message to print, and the
            // program exiting.

            Stream.Builder<String> unrecognizedSwitchListB  = Stream.builder();
            Stream.Builder<String> unrecognizedPackageListB = Stream.builder();

            TOP1:
            for (String arg : extraneousArgs)

                if (arg.startsWith("-")) unrecognizedSwitchListB.accept(arg);

                else
                {
                    for (BuildPackage bp : packageList) if (bp.nickName.equals(arg)) continue TOP1;
                    unrecognizedPackageListB.accept(arg);
                }

            // *** NEW-ADDITION: Check this list too - This "Extra For-Loop" is only here to ensure
            //     that the error message which is printed, includes all possible mistakes...

            TOP2:
            for (String arg : commandLine.getOptionValues(selectedOpt))
            {
                for (BuildPackage bp : packageList) if (bp.nickName.equals(arg)) continue TOP2;
                unrecognizedPackageListB.accept(arg);
            }

            // *** END-NEW-ADDITION: The "unrecognizedPackageListB" also includes the Package
            //     Nick-Names that Apache-CLI knows about...

            final String[] unrecognizedSwitches =
                unrecognizedSwitchListB.build().toArray(String[]::new);

            final String[] unrecognizedPackages =
                unrecognizedPackageListB.build().toArray(String[]::new);

            // Print an error message and exit if either of these lists are non-empty
            if ((unrecognizedSwitches.length + unrecognizedPackages.length) > 0)
                throw printMenuHelp(options, unrecognizedSwitches, unrecognizedPackages);
        }


        // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
        // 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_OPTION_SWITCH        = false,
            INCLUDE_JAR_IN_CP                   = false,
            SKIP_REMOVE_GCS_FILES_OPTION_SWITCH = false,
            OVERRIDE_TOGGLE_USE_XLINT_SWITCH    = false,
            OVERRIDE_TOGGLE_USE_XDIAGS_SWITCH   = false,
            EARLY_DEVELOPMENT_SWITCH            = false;

        // Get all processed / user-provided options
        final Option[] optArr = commandLine.getOptions();

        for (Option opt : optArr) switch (opt.getOpt())
        {
            case "NQB"  : NO_QUICK_BUILD_OPTION_SWITCH          = true; break;
            case "JCP"  : INCLUDE_JAR_IN_CP                     = true; break;
            case "SRG"  : SKIP_REMOVE_GCS_FILES_OPTION_SWITCH   = true; break;
            case "TXL"  : OVERRIDE_TOGGLE_USE_XLINT_SWITCH      = true; break;
            case "TXD"  : OVERRIDE_TOGGLE_USE_XDIAGS_SWITCH     = true; break;
            case "IEDP" : EARLY_DEVELOPMENT_SWITCH              = true; break;
            // default  : continue;
        }

        this.INCLUDE_JAR_IN_CP          = INCLUDE_JAR_IN_CP;
        this.SKIP_REMOVE_GCS_FILES      = SKIP_REMOVE_GCS_FILES_OPTION_SWITCH;
        this.INCLUDE_EARLY_DEV_PACKAGES = EARLY_DEVELOPMENT_SWITCH;

        // Only Main-Menu Option "Complete-Build-1" allows for writing to the "Release GCS Bucket"
        this.toReleaseOrDeveloper = this.MENU_CHOICE.equals("cb1");

        // Only Main-Menu Option "#4 - TAR & JAR" accepts the "JARONLY" argument
        final String optVal = commandLine.getOptionValue(selectedOpt);
        this.JAR_ONLY = (optVal != null) && optVal.equals("JARONLY");

        this.QUICKER_BUILD =
                (this.MENU_CHOICE.equals("cb1"))
            ||  (this.MENU_CHOICE.equals("cb2"))
            ||  (this.MENU_CHOICE.equals("cb3"))
            ? false
            : (! NO_QUICK_BUILD_OPTION_SWITCH);

        this.GCS_DIR = this.toReleaseOrDeveloper
            ? GCS_DIR_RELEASE
            : GCS_DIR_DEV;

        this.OVERRIDE_TOGGLE_USE_XLINT_SWITCH   = OVERRIDE_TOGGLE_USE_XLINT_SWITCH;
        this.OVERRIDE_TOGGLE_USE_XDIAGS_SWITCH  = OVERRIDE_TOGGLE_USE_XDIAGS_SWITCH;


        // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
        // More Error-Checking
        // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
        //
        // These simple error-checks are simply trying to inform the user when particular flags
        // may or may not be applied.  If, for instance, the user requested Main-Menu Option #4
        // - Tar & Jar Files - then also providing the switch -SRG would simply be an error.  The
        // value of these error-checks is that, when they are more rigorous, the error/help 
        // explanations that are spit-out in their faces make explaining what any of this doing
        // (at all), just that much easier to explain.
    
        if (this.INCLUDE_JAR_IN_CP)

            if (! MENU_CHOICE.equals("1")) throw printMenuHelp(
                options,
                "The " + BRED + "--putJarInCP" + RESET + " (-JCP) may only be used alongside " +
                "Main-Menu Option " + BRED + "--javac" + RESET + " (-1)"
            );

        // For -NQB, ONLY Main-Menu Options: -pb1 & -pb2, may receive this switch.
        if (NO_QUICK_BUILD_OPTION_SWITCH) 

            if (StrCmpr.equalsNAND(MENU_CHOICE, "pb1", "pb2")) throw printMenuHelp(
                options,
                "The " + BRED + "--noQuickBuild" + RESET + " (-NQB) switch may only be applied " +
                "to the Partial-Build Menu-Options " + BRED + "--partialAll" + RESET + " (-pb1) " +
                "and " + BRED + "--partialSome" + RESET + " (-pb2)"
            );

        // NOTE: Here, we need We DO NOT NEED TO TEST the value that was assigned to
        //       this.SKIP_REMOVE_GCS_FILES.  We need to check the value indicating whether or not
        //       the user passed the switch on the Command-Line.

        if (SKIP_REMOVE_GCS_FILES_OPTION_SWITCH)

            if (StrCmpr.equalsNAND(MENU_CHOICE, "cb2", "cb3")) throw printMenuHelp(
                options,
                "The Command-Switch " + BRED + "--skipRemoveGCSFiles" + RESET + " (-SRG) may " +
                "only be used in combination with Main-Menu Option " + BRED + "`--buildDevSMA`" +
                RESET + " (-cb2) or " + BRED + "`--buildDev`" + RESET + " (-cb3)"
            );

        if (this.OVERRIDE_TOGGLE_USE_XLINT_SWITCH || this.OVERRIDE_TOGGLE_USE_XDIAGS_SWITCH)

            if (! MENU_CHOICE.equals("1")) throw printMenuHelp(
                options,
                "Switches " + BRED + "--toggleDefaultXlint" + RESET + " (-TXL) and " + BRED +
                "--toggleDefaultXdiags" + RESET + " (-TXD) may only be used in combination with " +
                "Main-Menu Option " + BRED + "`--javac`" + RESET + " (-1)"
            );

        if (this.INCLUDE_EARLY_DEV_PACKAGES)

            if (StrCmpr.equalsXOR(MENU_CHOICE, "4", "6", "7", "cb1")) throw printMenuHelp(
                options,
                "The Command-Switch " + BRED + "--includeEarlyDev" + RESET + " (-IEDP) may " +
                "only be used in combination with some of the Main-Menu Options:\n" +
                "-1, -2, -3, -5, -8, -cb2, -cb3, -pb1, -pb2"
            );



        // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
        // Handle #1 & #21 - Package-NickNames / User-Specified Package-List
        // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
        // 
        // If the Main-Menu Option is followed by a list of String-Tokens, the only possible 
        // presumption is that they are a list of package nick-names (or Option #4, the "JARONLY")
        // String-Token Switch.
        //
        // Only Options #1 and #21 are allowed to accept the list of package nick-names

        final String[]  nickNames           = commandLine.getOptionValues(selectedOpt);
        final boolean   nickNamesProvided   = (nickNames != null) && (nickNames.length > 0);

        // This error would (should !) automatically caught by Apache, and wouldnever reach this
        // point.  This is just a variant of 'assert', and it's staying here for now.

        if (nickNamesProvided && (! pkgNickNamesPossible)) throw new UnreachableError();

        // A temporary list that is needed to merge the two different sources of Package Nick-Name
        // arguments.  Since I simply cannot get Apache's Option-Argument thing to work with a
        // configuration of ZERO, ONE or MANY Option-Arguments, I have to presume that it isn't
        // possible.  As such, the source of Package Nick-Names are the "getOptionValues" **AND**
        // **ALSO** the Extraneous-Options too!
        //
        // Merge those two lists, and then use that merged list as the package nick-names list.
        // Remember that only options "1" (javac) and "pb2" (partial-build 2) even accept package
        // nick-names lists.  All of the others do not accept any arguments at all.

        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;
    }


    // ********************************************************************************************
    // ********************************************************************************************
    // Help-Menu Printing
    // ********************************************************************************************
    // ********************************************************************************************


    // This happens when the Apache.CLI finds a Switch-Error
    private UnreachableError printMenuHelp(Options options, ParseException pe)
    {
        printMenuHelp(options);
        System.out.println(pe.getMessage());
        System.exit(1);
        return null; // javac is too noisy
    }

    private UnreachableError printMenuHelp(Options options, String explanation)
    {
        printMenuHelp(options);
        System.out.println(explanation);
        System.exit(1);
        return null; // javac is too noisy
    }

    // This Error-Message is printed/written when the user failed to provide at least one of the
    // Main-Menu Switch-Options.

    private UnreachableError printMenuHelp(Options options, MissingOptionException moe)
    {
        printMenuHelp(options);

        System.out.println(
            BRED + "You must select exactly one of the primary Build Options:\n\n" + RESET +
            BYELLOW + "    Build-Step Options:\n" + RESET +
            "        -1 <OPTIONAL-PKG-LIST> | -2 | -3 | -4 <JARONLY> | -5 | -6 | -7 | -8 |\n\n" +
            BYELLOW + "    Complete-Build Options:\n" + RESET +
            "        -cb1 | -cb2 | -cb3 |\n\n" +
            BYELLOW + "    Partial-Build Options:\n" + RESET +
            "        -pb1 | -pb2 <OPTIONAL-PKG-LIST> |\n\n" +
            BYELLOW + "    Links-Chcker Build:\n" + RESET +
            "        -LC\n\n" +
            BCYAN + "Additional switches [-JCP, -NQB, -SRG, -TXD, -TXL, -IEDP], may also be added\n" + RESET
        );

        System.exit(1);
        return null; // javac is too noisy
    }

    private UnreachableError printMenuHelp(Options options, String[] unrecognizedSwitches)
    {
        printMenuHelp(options);

        System.out.println(
            "You have passed one or more spurious or unrecognized options:\n" +
            BRED + "Unknown Command-Line Switches Include: " + RESET +
            '[' + String.join(", ", unrecognizedSwitches) + ']' + '\n'
        );

        System.exit(1);
        return null; // javac is too noisy
    }

    private UnreachableError printMenuHelp
        (Options options, String[] unrecognizedSwitches, String[] unrecognizedPackages)
    {
        printMenuHelp(options);

        if (unrecognizedSwitches.length > 0) System.out.println(
            "You have passed one or more spurious or unrecognized options:\n" +
            BRED + "Unknown Command-Line Switches: " + RESET +
            '[' + String.join(", ", unrecognizedSwitches) + ']' + '\n'
        );

        if (unrecognizedPackages.length > 0) System.out.println(
            "You have passed one or more unrecognized Package Nick-Names:\n" +
            BRED + "Unknown Package Nick-Names: " + RESET +
            '[' + String.join(", ", unrecognizedPackages) + ']' + '\n'
        );

        System.exit(1);
        return null; // javac is too noisy
    }

    // This is the "printMenuHelp" portion of the output-printer that is constant / consisten for
    // all of the previous print-menu help-functions above.

    private static String descriptionCommandLine = 
         "java MyBuildImpl -1 <PKG-LIST> | -2 | ... | -8 | -cb1 | -cb2 | -cb3 | -pb1 | " +
        "-pb2 <PKG-LIST> | -LC\n" +
    "    [-JCP, -NQB, -SRG, -TXD, -TXL, -IEDP]";

    private static void printMenuHelp(Options options)
    {
        // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
        // Leave this here, I may try to bring this back one day, just not right now
        // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***

        System.out.println(
            // BCYAN + "Old Build Menu:\n" + RESET +
            HAND_TYPED_MAN_PAGE
            // BCYAN + "\nApache Build Menu:\n" + RESET
        );

        /*
        HelpFormatter hf = new HelpFormatter();
        hf.setWidth(115);
        hf.setLeftPadding(6);
        hf.setOptionComparator(CLI::compareOptions);
        */

        // Playing with these.  They are a little silly.  Leave this here, just to remember what
        // Apache.CLI even does!
        //
        // hf.setLongOptPrefix("^");
        // hf.setLongOptSeparator("#");
        // hf.setOptPrefix("@");
        // hf.setSyntaxPrefix("!!");
    
        // hf.printHelp(descriptionCommandLine, options);

        // System.out.println();
    }

    // This long-winded thing is, apparently, the only way I could get Apache.CLI to order the
    // Menu-Options using the "HelpFormatter" above.  This is a java.util.Comparator
    // Function-Pointer that actually "sorts" the Menu-Options for the Menu-Options-Printer method
    // directly above.
    //
    // It sorts them to, sort of, emphasize, the Main-Menu Mandatory Options versus the
    // Optional-Options.  These "Optional-Options" are the little "Extra-Switches" listed at the
    // very end of the Menu.

    private static int compareOptions(Option o1, Option o2)
    {
        final String name1          = o1.getOpt();
        final String name2          = o2.getOpt();

        // The first 8 Build-Steps and 3 Complete-Build-Steps would automatically be properly
        // sorted at the TOP OF THE LIST - using the Nature-Comparison-Order ANYWAY!  There is no
        // need to "subvert" the Natural-Sort-Order for Steps 1..8 and cb1, cb2 or cb3.  They are 
        // already going to be sorted at the top of the list anyways, without any sort-order
        // intervention.

        final boolean naturalSort1  = (name1.length() == 1) || name1.startsWith("cb");
        final boolean naturalSort2  = (name2.length() == 1) || name2.startsWith("cb");

        if (naturalSort1 || naturalSort2) return name1.compareToIgnoreCase(name2);

        // The two Partial-Build Main-Menu Options' Natural-Sort Order would innappropriately place
        // them further down the Main-Menu than I would like them to be placed.  Therefore, this 
        // comparator has to "intervene" and make sure they are next on the Comparitor's sort /
        // return list - located DIRECTLY AFTER the three -cb (Complete-Build) Menu-Options.

        final boolean pb1 = name1.startsWith("pb");
        final boolean pb2 = name2.startsWith("pb");

        if (pb1 && pb2) return name1.compareToIgnoreCase(name2);

        if (pb1) return -1;
        if (pb2) return 1;

        // The last intervention is to place the "Links Check" Menu-Option DIRECTLY AFTER the
        // "Partial-Build" (-pb1 & -pb2) Menu-Options.

        final boolean lc1 = name1.startsWith("LC");
        final boolean lc2 = name2.startsWith("LC");

        if (lc1) return -1;
        if (lc2) return 1;

        // These are the "Extra-Switches" which add some features to make Life easier for me.
        // These are placed at the VERY END of the menu, and their individual Menu-Placement / 
        // Sort-Order is completely irrelevant to me.  So as long as these are at the end of the
        // list, from that point, they may be placed in their Natural-Order Locations.

        return name1.compareToIgnoreCase(name2);
    }

    static final String HAND_TYPED_MAN_PAGE =
        BYELLOW + "\n\tJava Compiler Step:" + RESET +
        "\n\t\t-1  -> Compile [Optional: Package-Nicknames)" +

        BYELLOW + "\n\n\tBuild Steps:" + RESET +
        "\n\t\t-2   -> JavaDoc" +
        "\n\t\t-3   -> Upgrader" +
        "\n\t\t-4   -> Build TAR's & JAR [Optional: 'JARONLY']" +
        "\n\t\t-5   -> Copy to GCS: 'javadoc" + File.separator + "' directory" +
        "\n\t\t-6   -> Copy to GCS: '.tar' and '.jar' files" +
        "\n\t\t-7   -> Copy to GCS: logs" +
        "\n\t\t-8   -> GSUTIL.SMA(GCS_DIR + \"**\", 150);" +

        BYELLOW + "\n\n\tComplete Build (Composite Processes):" + RESET +
        "\n\t\t-cb1 -> STEPS 2 through 7     [Pushes-To: GCP-Release]" +
        "\n\t\t-cb2 -> STEPS 2 through 8     [Pushes-To: GCP-Developer] w/ Set-Max-Age " +
        "\n\t\t-cb3 -> STEPS 2 through 7     [Pushes-To: GCP-Developer]" +

        BYELLOW + "\n\n\tPartial-Debuging Build, (Push-To: GCP-Developer only):" + RESET +
        "\n\t\t-pb1 -> SETPS 2 and 3         [Doc Only]" +
        "\n\t\t-pb2 -> STEPS 2, 3, 5, and 8  [Doc, Sync & Max-Age. Optional: Package-Nicknames]" +

        BYELLOW + "\n\n\tLinks-Checker:" + RESET +
        "\n\t\t-LC  -> STEPS 2 and 3, WITH-LINKS-CHECK" +

        BYELLOW + "\n\n\tAdditional Side Options:" + RESET +
        "\n\t\t-JCP,--putJarInCP             " + descriptionNQB +
        "\n\t\t-NQB,--noQuickBuild           " + descriptionJCP +
        "\n\t\t-SRG,--skipRemoveGCSFiles     " + descriptionSRG +
        "\n\t\t-TXD,--toggleDefaultXdiags    " + descriptionTXD +
        "\n\t\t-TXL,--toggleDefaultXlint     " + descriptionTXL +
        "\n\t\t-IEDP,--includeEarlyDev       " + descriptionIEDP +

        "\n";
}