package Torello.Java.Build;

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

import Torello.Java.StringParse;
import Torello.Java.StrCSV;

import Torello.Java.Additional.Ret2;

import java.util.function.Predicate;
import java.io.IOException;

/**
 * Decide which User-Provided Packages will be put through the various Build-Stages.
 */
@Torello.JavaDoc.StaticFunctional
public class Packages
{
    private Packages() { }

    /**
     * Used in the Class {@link Builder}-Constructor to specify, exactly, which packages may or may
     * not be processed during an invocation of that class' {@link Builder#build() build} method.
     * 
     * @param cli The Object that represents / contains the switches and User-Requests that were
     * obtained at the Command-Line from the Command-Line Parser Object {@link CLI}.
     * 
     * @param usersBuildPackageList The list of {@link BuildPackage} instances that were passed to
     * the User-Configuration Class {@link Config}.  The reference passed to this parameter is the
     * exact same reference that is found in {@link Config#packageList}.
     * 
     * @return This, essentially, returns the exact same input list, but after it has been divided
     * into two sets - those packages that are going to be included in the Build, and any packages
     * that are not part of the build.
     * 
     * <BR /><BR />The packages that are 'removed' from the build are:
     * 
     * <BR /><BR /><UL CLASS=JDUL>
     *
     * <LI> <B>{@link BuildPackage#EARLY_DEVELOPMENT Early-Development} Packages</B>
     *      <BR />These are packages which are not completed yet, and are not ready for
     *      publication &amp; distribution.
     *      <BR /><BR /></LI>
     *
     * <LI> <B>{@link BuildPackage#QUICKER_BUILD_SKIP Skip-On-Quick-Build} Packages</B>
     *      <BR />These are packages which are aren't necessarily imperative for the
     *      proper functioning of JAR, and for speed and a faster development time can be
     *      eliminated from your {@code '.jar'} when focusing on other parts of the build.
     *      </LI>
     *
     * </UL>
     * 
     * <BR /><BR /><B CLASS=JDDescLabel>Inclusion Decisions:</B>
     * 
     * <BR />The decision that remove packages from the list of "Packages to Process
     * in the Build" can be reversed at the Command-Line using the {@code '-NQB'} (No Quick Build)
     * or the {@code '-IEDP'} (Include Early-Development Packages.)
     * 
     * <BR /><BR />Utlimately this method returns two lists, contained by an instance of
     * {@link Ret2}.  The instances of {@link BuildPackage} that are going to be processed during
     * by {@link Builder} are in one list, and the {@code BuildPackage} instances to be skipped are
     * in the second list.
     * 
     * <BR /><BR /><UL CLASS=JDUL>
     * 
     * <LI> <B>{@code Ret2.a: ReadOnlyList<BuildPackage>}</B>
     *      <BR />The list of packages to be processed in this build.
     *      <BR /><BR /></LI>
     * 
     * <LI> <B>{@code Ret2.b: ReadOnlyList<BuildPackage>}</B>
     *      <BR />The list of packages to that are being skipped in this build.
     *      </LI>
     * 
     * </UL>
     */
    public static Ret2
        <
            ReadOnlyList<BuildPackage>,
            ReadOnlyList<BuildPackage>
        >
        packagesInThisBuild
        (CLI cli, BuildPackage[] usersBuildPackageList)
    {
        // This is a little complicated.  All this is doing is "merging" a suite of User-Provided
        // configurations from about three different places.
        // 
        // The class "BuildPackage" allows the user to configure settings for the packages.  One of
        // those settings allows a user to assert that a package is a "Skip if Quick Build."  In my
        // world all that is talking about is the "Torello.Browser" Package, which:
        //
        //      1) Takes for ever to compile
        //      2) Takes even longer to run the Java-Doc (and even longer for the upgrader)
        //      3) MOST-IMPORTANTLY: Never changes at all, because i'm not working on it right now.
        //         As a result, pretending it doesn't exist, except when compiling with -cb1
        //         "Complete Build 1" (The actual "Release Directory"), makes working a lot easier
        //
        // Class CLI also allows users to configure stuff by passing switches.  It's mechanisms
        // involve arguments passed to the "String[] argv" parameter via the
        // "public static void main" method.
        //
        // In Java-HTML, as of March 2024, the CSS Tokenizer (which is going to have extremely
        // limited use, since "parsing CSS" is several orders of magnitude less useful than parsing
        // HTML) - ... the "CSS Tokenizer" is an "Early Development" package.  Early Development
        // packages have almost the same behavior, they are left out completely (just like the
        // Quick-Build packages) - except when they are explicity requested.
        //
        // ========================================================================================
        // NOTE: "QUICK_BUILD" and "EARLY_DEVELOPMENT" packages are treated as if they just don't
        //       exist, unless the user has made specific requests for them at the command line CLI
        // ========================================================================================
        //
        // If a package isn't going to be processed during the build, it is placed into Ret2.b

        final boolean IS_FULL_COMPILE = (cli.userSpecifiedPackages == null);

        final Predicate<BuildPackage> FILT = (BuildPackage bp) ->
        {
            if (cli.QUICKER_BUILD) if (bp.skipIfQuickerBuild)

                return IS_FULL_COMPILE
                    ? false
                    : cli.userSpecifiedPackages.contains(bp);

            if (bp.earlyDevelopment)
            {
                if (cli.INCLUDE_EARLY_DEV_PACKAGES) return true;

                return IS_FULL_COMPILE
                    ? false
                    : cli.userSpecifiedPackages.contains(bp);
            }

            return true;
        };

        final ReadOnlyArrayList<BuildPackage> packagesIncluded =
            new ReadOnlyArrayList<BuildPackage>(FILT, usersBuildPackageList);

        final ReadOnlyArrayList<BuildPackage> packagesEliminated = 
            new ReadOnlyArrayList<BuildPackage>(FILT.negate(), usersBuildPackageList);

        return new Ret2<>(packagesIncluded, packagesEliminated);
    }

    /**
     * This determines which packages should be re-compiled in the Stage 1 Build-Class
     * {@link S01_JavaCompiler}.
     * 
     * @param builder This instance contains all information obtained from the User via the
     * User-Settings class {@link Config}, and information obtained via the Command-Line
     * Interface {@link CLI}.
     * 
     * @return The list of packages whose files are to be recompiled, based on the User-Settings
     * provided class {@link Config}, and the User-Request that were made at the {@link CLI}, 
     * Command-Line Interface
     */
    public static ReadOnlyList<BuildPackage> packagesToCompile(Builder builder) throws IOException
    {
        // It is important to "get" the BuildPackage Configuration-Flags.  
        //
        // The value of BuildPackge.mustReCompile is defined in (surprise) class BuildPackage, as
        // follows, here:
        //
        // this.earlyDevelopment   = (flags & EARLY_DEVELOPMENT) >= 1;
        // this.skipIfQuickerBuild = (flags & QUICKER_BUILD_SKIP)  >= 1;
        // 
        // this.mustReCompile =
        //         (! this.earlyDevelopment)
        //     &&  (! this.skipIfQuickerBuild)
        //     &&  ((flags & DO_NOT_RECOMPILE) == 0); // == 0 implies the "NOT" of the flag
        //
        // FINALLY: The cli.userSpecifiedPackages is literally just the Package-NickNames tht are
        //          provided to class CLI via the "public static void main" method that gets it.

        final boolean IS_FULL_COMPILE = (builder.cli.userSpecifiedPackages == null);

        final Predicate<BuildPackage> FILT = (builder.cli.INCLUDE_EARLY_DEV_PACKAGES)
            ? (BuildPackage bp) -> bp.mustReCompile || bp.earlyDevelopment
            : (BuildPackage bp) -> bp.mustReCompile;

        final ReadOnlyList<BuildPackage> packagesToCompile = IS_FULL_COMPILE
            ? new ReadOnlyArrayList<>(builder.packageList, FILT, builder.packageList.size())
            : builder.cli.userSpecifiedPackages;

        return packagesToCompile;
    }

    /**
     * This determines which packages should be run through {@code 'javadoc'}, in the Stage 2
     * Build-Class {@link S02_JavaDoc}.
     * 
     * @param builder This instance contains all information obtained from the User via the
     * User-Settings class {@link Config}, and information obtained via the Command-Line
     * Interface {@link CLI}.
     * 
     * @return The list of packages whose files are to be sent to the {@code javadoc} Tool, based
     * on the User-Settings provided class {@link Config}, and the User-Request that were made at
     * the {@link CLI}, Command-Line Interface.
     */
    public static ReadOnlyList<BuildPackage> packagesToJavaDoc(Builder builder)
    {
        // Copied from the class `BuildPackage
        //
        // this.mustDocument        = (flags & DO_NOT_DOCUMENT)     == 0; // The "NOT" of the flag
        // this.earlyDevelopment    = (flags & EARLY_DEVELOPMENT)   >= 1;
        // this.skipIfQuickerBuild  = (flags & QUICKER_BUILD_SKIP)  >= 1;

        final Predicate<BuildPackage> FILT = (BuildPackage pkg) -> pkg.mustDocument;

        final ReadOnlyList<BuildPackage> ret = new ReadOnlyArrayList<>
            (builder.packageList, FILT, builder.packageList.size());

        return ret;
    }
}