package Torello.Java.Build;

import Torello.HTML.HTMLPage; // needed for a JavaDoc '@link'

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

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

import static Torello.Java.C.*;

import java.io.File;
import java.util.TreeSet;
import java.util.stream.Stream;

/**
 * This User-Data class is used to describe the Java-Packages included inside of a Java Project.
 * 
 * <BR /><BR /><B CLASS=JDDescLabel>Java-HTML JAR BuildPackage instances:</B>
 * 
 * <BR />You may view the list of packages that are used to build the Java-HTML JAR-Library
 * here, in the link below:
 * 
 * <BR /><BR /><A HREF='hilite-files/MyPackages.java.html'>MyPackages.java</A>
 */
public class BuildPackage
{
    // ********************************************************************************************
    // ********************************************************************************************
    // Static Flag-Fields
    // ********************************************************************************************
    // ********************************************************************************************


    /**
     * This flag may be attached to one of your {@code BuildPackage} instances to signify that the
     * package being flagged should not ever be re-compiled when Build-Stage 1 ({@code 'javac'}) is
     * executing - <I>unless the package's nick-name has been explicity specified at the Command
     * Line Interface</I>.
     * 
     * <BR /><BR />This flag can be an invaluable tool for speeding up build times be eliminating
     * the compilation for Source-Files whose code is not changing and is not dependent on the
     * Source-Files inside your project.
     * 
     * <BR /><BR /><B CLASS=JDDescLabel>For Instance, Java-HTML:</B>
     * 
     * <BR />In the Java-HTML {@code '.jar'} File, the external-imports that are included such as
     * the Glass-Fish JSON Processor, and the Apache CLI Tools have Source-Files that do not ever
     * need to be recompiled.  Those packages are included in this {@code '.jar'} file's
     * documentation, but when this project is built, the Compiler Build-Stage will skip the
     * compilation of the Source-Files in those Packages.
     */
    public static final byte DO_NOT_RECOMPILE = 1;

    /**
     * This flag may be attached to one of your {@code BuildPackage} instances to signify that the
     * package being flagged should not ever be documented when Build-Stage 2 ({@code 'javadoc'})
     * is executing.
     * 
     * <BR /><BR />When this flag is attached to a {@code BuildPackage}, there will simply be no
     * documentation generated for that package.
     * 
     * <BR /><BR /><B CLASS=JDDescLabel>For Instance, Java-HTML:</B>
     * 
     * <BR />This Project's {@code '.jar'} File includes several classes that act as Internal
     * Processors for the Java-Doc Upgrader Tool.  Those classes are all part of a root package
     * known as {@code JDUInternal}.
     * 
     * <BR /><BR />Because the Source-Code in these classes serves no purpose whatsoever as a part
     * of any kind of "External API", the methods and fields of those classes are not documented.
     * The {@code BuildPackage} instance for the {@code JDUInternal} Package has been flagged with
     * this flag {@code DO_NOT_DOCUMENT}
     */
    public static final byte DO_NOT_DOCUMENT = DO_NOT_RECOMPILE << 1;

    /**
     * This is a special flag that may be used to signify that a particular {@code BuildPackage}
     * instance actually refers to a tree of packages, rather than just a single package.
     * 
     * <BR /><BR />This flag works very well with the {@link #DO_NOT_DOCUMENT} Flag.
     * 
     * <BR /><BR /><B CLASS=JDDescLabel>For Instance, Java-HTML:</B>
     * 
     * <BR />Again, the internal Java-Doc Upgrader Classes, rooted in package {@code JDUInternal},
     * actually form a tree of packages that are ultimately included in the {@code '.jar'} File.
     */
    public static final byte HAS_SUB_PACKAGES = DO_NOT_DOCUMENT << 1;

    /**
     * This is a flag that can be used to boost Build-Times in a way quite similar to the 
     * {@link #DO_NOT_RECOMPILE} flag.  When a {@code BuildPackage} instance is flagged with 
     * {@code QUICKER_BUILD_SKIP}, if a user is performing a "Partial Build" using one of the
     * Partial-Build Flags ({@code -pb1} and {@code -pb2}), then that package will simply be 
     * eliminated from the Build.
     * 
     * <BR /><BR />For packages that are not necessarily external and independent packages, but
     * are disjoint enough such that they do not need to be recompiled or documented in most 
     * situations, then this flag can help boost Build-Speed during development.
     * 
     * <BR /><BR /><B CLASS=JDDescLabel>For Instance, Java-HTML:</B>
     * 
     * <BR />The Java-HTML {@code '.jar'} includes an Experimental Headless-Browser
     * Package.  The {@code BuildPackage} instance that models that package is flagged with the
     * {@code QUICKER_BUILD_SKIP}.  This means that during development, unless a Full Release
     * Build has been invoked (Build-Switch {@code '-cb1'}), the Browser-Package is simply ignored.
     * 
     * <BR /><BR />It is not compiled by Stage 1; it is not documented by the {@code 'javadoc'}
     * stage, and its documentation pages are not upgraded.  Because that package was generated by
     * a Code-Generator, and is extremely lengthy and doesn't change, it doesn't need to be 
     * included in the Build-Process at all unless a Full-Release Build is being invoked.
     * 
     * <BR /><BR />Note that the Build-Switch {@code '-NQB'} can override the elimination of 
     * packages that have been flagged in this way.
     */
    public static final byte QUICKER_BUILD_SKIP = HAS_SUB_PACKAGES << 1;

    /**
     * This can be used to request that the class files for a Java Package not be included in the
     * {@code '.jar'} File generated for that package.
     * 
     * <BR /><BR /><B CLASS=JDDescLabel>For Instance, Java-HTML:</B>
     * 
     * <BR />There is a proprietary, internal, Builder Package Hierarchy that is only used for 
     * improving this particular package.  The classes in package {@code Torello.BuildJAR} are,
     * therefore, flagged with the {@code 'DO_NOT_JAR'} flag.
     * 
     * <BR /><BR />A cursory inspection of the Java-HTML {@code '.jar'} File will reveal that
     * there is not package named {@code Torello.BuildJAR} inside the {@code '.jar'} File.  This is
     * because that package contains proprietary and internal classes that serve no purpose 
     * whatsoever outside of the Build-Process.
     */
    public static final byte DO_NOT_JAR = QUICKER_BUILD_SKIP << 1;

    /**
     * Can be used to flag a package as "Under Development."  Packages flagged as such will not be
     * included in the Build unless explicity requested.
     * 
     * <BR /><BR /><B CLASS=JDDescLabel>For Instance, Java-HTML:</B>
     * 
     * <BR />The most recent addition to Java-HTML has been the package {@code Torello.CSS}.
     * It is currently under development and therefore wholly eliminated from the Build except
     * when it has been explicity requested.
     * 
     * <BR /><BR />The elimination of packages flagged with the {@code 'EARLY_DEVELOPMENT'} flag 
     * can be overriden using the Build Command-Line Switch {@code '-IEDP'}, which simply stands 
     * for "Include Early Development Packages".
     */
    public static final byte EARLY_DEVELOPMENT = DO_NOT_JAR << 1;


    // ********************************************************************************************
    // ********************************************************************************************
    // Static Fields
    // ********************************************************************************************
    // ********************************************************************************************


    // This can be important
    public static final boolean DEBUGGING = false;

    // This is ubiquitous in Build-Stuff
    private static final String FS = File.separator;

    // For (most) packages, which do not have "Helper Packages"
    private static final ReadOnlyList<String> EMPTY_LIST = ReadOnlyList.of();


    // ********************************************************************************************
    // ********************************************************************************************
    // Instance Fields
    // ********************************************************************************************
    // ********************************************************************************************


    /** This package's full-name. */
    public final String fullName;

    /** This package's class-path location within the File-System. */
    public final String classPathLocation;

    /** This package's root-directory within the File-System. */
    public final String pkgRootDirectory;

    /** A Nick-Name that may be used when trying to request this package at the CLI */
    public final String nickName;

    /**
     * Indicates that this package's Source-Code Directory has an {@code 'upgrade-files/'}
     * sub-directory.  The {@code 'upgrade-files/'} directory stores myriad configurations that are
     * utilized by the Java-Doc Upgrader Tool, which is executed in Build-Stage 3.
     * 
     * <BR /><BR />This field is assigned as follows:
     * 
     * <BR /><DIV CLASS=SNIP>{@code
     * File f = new File(this.pkgRootDirectory + "upgrade-files" + FS);
     * 
     * this.hasUpgradeFilesDir = f.exists() && f.isDirectory();
     * }</DIV>
     */
    public final boolean hasUpgradeFilesDir;

    /**
     * Indicates that this package's Source-Code Directory has a {@code 'package-source/'}
     * sub-directory containing {@code '.java'} Files.  The {@code 'package-source/'} directory
     * can be used to organize and categorize {@code '.java'} Files within a single Java Package 
     * so that they are not all lumped together in a single Java-Package Directory.
     * 
     * <BR /><BR />This field is assigned as follows:
     * 
     * <BR /><DIV CLASS=SNIP>{@code
     * f = new File(this.pkgRootDirectory + "package-source" + FS);
     * 
     * this.hasPackageSourceDir = f.exists() && f.isDirectory();
     * }</DIV>
     */
    public final boolean hasPackageSourceDir;

    /**
     * This field indicates whether or not the {@link #DO_NOT_RECOMPILE} flag was assigned to
     * {@code 'this'} instance of {@code BuildPackage}.  This field's value is assigned, in this
     * class' constructor, as below:
     * 
     * <BR /><DIV CLASS=SNIP>{@code
     * this.mustReCompile = (flags & DO_NOT_RECOMPILE) == 0;
     * }</DIV>
     * 
     * @see #DO_NOT_RECOMPILE
     */
    public final boolean mustReCompile;

    /**
     * This field simply indicates whether or not the {@link #DO_NOT_DOCUMENT} was assigned to
     * {@code 'this'} instance of {@code BuildPackage}.  This field's value is assigned, in this
     * class' constructor, as below:
     * 
     * <BR /><DIV CLASS=SNIP>{@code
     * this.mustDocument = (flags & DO_NOT_DOCUMENT) == 0;
     * }</DIV>
     * 
     * @see #DO_NOT_DOCUMENT
     */
    public final boolean mustDocument;

    /**
     * This field simply indicates whether or not the {@link #DO_NOT_JAR} was assigned to
     * {@code 'this'} instance of {@code BuildPackage}.  This field's value is assigned, in this
     * class' constructor, as below:
     * 
     * <BR /><DIV CLASS=SNIP>{@code
     * this.doNotJAR = (flags & DO_NOT_JAR) >= 1;
     * }</DIV>
     * 
     * @see #DO_NOT_JAR
     */
    public final boolean doNotJAR;

    /**
     * This field simply indicates whether or not the {@link #HAS_SUB_PACKAGES} was assigned to
     * {@code 'this'} instance of {@code BuildPackage}.  This field's value is assigned, in this
     * class' constructor, as below:
     * 
     * <BR /><DIV CLASS=SNIP>{@code
     * this.hasSubPackages = (flags & HAS_SUB_PACKAGES) >= 1;
     * }</DIV>
     * 
     * @see #HAS_SUB_PACKAGES
     */
    public final boolean hasSubPackages;

    /**
     * This field simply indicates whether or not the {@link #QUICKER_BUILD_SKIP} was assigned to
     * {@code 'this'} instance of {@code BuildPackage}.  This field's value is assigned, in this
     * class' constructor, as below:
     * 
     * <BR /><DIV CLASS=SNIP>{@code
     * this.skipIfQuickerBuild = (flags & QUICKER_BUILD_SKIP) >= 1;
     * }</DIV>
     * 
     * @see #QUICKER_BUILD_SKIP
     */
    public final boolean skipIfQuickerBuild;

    /**
     * This field simply indicates whether or not the {@link #EARLY_DEVELOPMENT} was assigned to
     * {@code 'this'} instance of {@code BuildPackage}.  This field's value is assigned, in this
     * class' constructor, as below:
     * 
     * <BR /><DIV CLASS=SNIP>{@code
     * this.earlyDevelopment = (flags & EARLY_DEVELOPMENT) >= 1;
     * }</DIV>
     * 
     * @see #EARLY_DEVELOPMENT
     */
    public final boolean earlyDevelopment;

    /**
     * Helper packages may be passed as parameters to the {@code BuildPackage} constructor.  All a
     * "Helper Package" is is a sub-directory of the Package-Directory that contains additional
     * classes that are germaine to the classes in this package.
     * 
     * <BR /><BR />The classes in a Helper-Package will not be documented by {@code 'javadoc'}, nor
     * will they be (obviously) be upgrader by the Stage 3 Build-Class performing the JavaDoc
     * Upgrade.
     * 
     * <BR /><BR />Instead, these classes will be compiled by the {@code 'javac'}, and included,
     * quietly, in the final {@code '.jar'} File produced by this Build.  This can be a great way 
     * to add simple classes that are required for an API Class to fully function, but do not 
     * actually need to be documented and included in the API themselves.
     * 
     * <BR /><BR />A cursory inspection of the contents of the Java-HTML {@code '.jar'}
     * Distribution should reveal, for instance the HTML Helper-Package
     * {@code 'Torello.HTML.parse'}, which does the actual parsing for the HTML Parsing class 
     * {@link HTMLPage}.  This class is fundamental and necessary to the operation of the HTML 
     * Package, but is largely useless in the API that's exported to the end user.
     * 
     * <BR /><BR />This field's value is assigned by this class' constructor, as below:
     * 
     * <BR /><DIV CLASS=SNIP>{@code
     * this.helperPackages = (helperPackages == null) || (helperPackages.length == 0)
     *      ? EMPTY_LIST
     *      : new ReadOnlyArrayList(
     *          0,
     *          (String subDirName) -> this.pkgRootDirectory +
     *              (subDirName.endsWith(FS) ? subDirName : (subDirName + FS)),
     *          helperPackages
     *      );
     * }</DIV>
     */
    public final ReadOnlyList<String> helperPackages;


    // ********************************************************************************************
    // ********************************************************************************************
    // Lone Constructor
    // ********************************************************************************************
    // ********************************************************************************************


    /**
     * Constructs an instance of this class.
     * 
     * @param fullName The full name of the package.  This package, for instance, is named
     * {@code Torello.Java.Build}.
     * 
     * @param classPathLocation The root class-path location
     * 
     * @param nickName A nick-name for this package that may be passed at the Command-Line
     * Interface when it is necessary to specify that this package be included in the Build-Proces.
     * 
     * @param flags The <B>{@code Boolean-OR}</B> of all flags being assigned to this package.
     * 
     * @param helperPackages A list of any and all sub-directory packages to be included in this
     * {@code '.jar'} upon which this package depends.  This list must contain {@code String's}
     * that name actual sub-directories of the package-directory that contains the source-files
     * for this package.
     * 
     * @throws IllegalArgumentException This exception throws under the following circumstances:
     * 
     * <BR /><BR /><UL CLASS=JDUL>
     * <LI> If {@link #mustDocument} and {@link #hasSubPackages} are both, simultaneously, set</LI>
     * <LI> If any of the "Helper Packages" do not name valid sub-directories of the primary
     *      package-directory
     *      </LI>
     * </UL>
     */
    public BuildPackage(
            final String      fullName,
            final String      classPathLocation,
            final String      nickName,
            final int         flags,
            final String...   helperPackages
        )
    {
        this.fullName = fullName;

        if (StrCmpr.equalsXOR(classPathLocation, ".", ""))
            this.classPathLocation  = "";
        else if (! classPathLocation.endsWith(FS))
            this.classPathLocation = classPathLocation + FS;
        else
            this.classPathLocation = classPathLocation;

        this.nickName           = nickName;
        this.earlyDevelopment   = (flags & EARLY_DEVELOPMENT)   >= 1;
        this.skipIfQuickerBuild = (flags & QUICKER_BUILD_SKIP)  >= 1;
        this.mustReCompile      = (flags & DO_NOT_RECOMPILE)    == 0; // The "NOT" of the flag
        this.mustDocument       = (flags & DO_NOT_DOCUMENT)     == 0; // The "NOT" of the flag
        this.doNotJAR           = (flags & DO_NOT_JAR)          >= 1;
        this.hasSubPackages     = (flags & HAS_SUB_PACKAGES)    >= 1;
        this.pkgRootDirectory   = classPathLocation + fullName.replace(".", FS) + FS;

        this.helperPackages = (helperPackages == null) || (helperPackages.length == 0)
            ? EMPTY_LIST
            : new ReadOnlyArrayList<>(
                0,
                (String subDirName) -> this.pkgRootDirectory +
                    (subDirName.endsWith(FS) ? subDirName : (subDirName + FS)),
                helperPackages
            );

        File f = null;

        for (String pkgDirName : this.helperPackages)
        {
            f = new File(pkgDirName);

            if ((! f.exists()) || (! f.isDirectory())) throw new IllegalArgumentException(
                "Helper Package [" + pkgDirName + "] specifies a directory that either doesn't " +
                "exist or is a file, rather than a directory:\n" + f.toString()
            );
        }

        f = new File(this.pkgRootDirectory + "upgrade-files" + FS);

        this.hasUpgradeFilesDir = f.exists() && f.isDirectory();

        f = new File(this.pkgRootDirectory + "package-source" + FS);

        this.hasPackageSourceDir = f.exists() && f.isDirectory();

        if (this.mustDocument && this.hasSubPackages) throw new IllegalArgumentException
            ("this.mustDocument AND this.hasSubPackages");
    }


    // ********************************************************************************************
    // ********************************************************************************************
    // toString
    // ********************************************************************************************
    // ********************************************************************************************


    /**
     * Stringify an instance of this class.
     * @return a Java {@code String} representation of this class.
     */
    public String toString()
    {
        final int LEN = 22;

        final String CPL = (classPathLocation.length() == 0)
            ? BGREEN + "Current Working Directory" + RESET
            : classPathLocation;

        return 
            StringParse.rightSpacePad("fullName:", LEN)             + fullName              + '\n' +
            StringParse.rightSpacePad("classPathLocation:", LEN)    + CPL                   + '\n' +
            StringParse.rightSpacePad("pkgRootDirectory:", LEN)     + pkgRootDirectory      + '\n' +
            StringParse.rightSpacePad("nickName:", LEN)             + nickName              + '\n' +
            StringParse.rightSpacePad("hasUpgradeFilesDir:", LEN)   + hasUpgradeFilesDir    + '\n' +
            StringParse.rightSpacePad("hasPackageSourceDir:", LEN)  + hasPackageSourceDir   + '\n' +
            StringParse.rightSpacePad("mustReCompile:", LEN)        + mustReCompile         + '\n' +
            StringParse.rightSpacePad("mustDocument:", LEN)         + mustDocument          + '\n' +
            StringParse.rightSpacePad("hasSubPackages:", LEN)       + hasSubPackages        + '\n' +
            StringParse.rightSpacePad("skipIfQuickerBuild:", LEN)   + skipIfQuickerBuild    + '\n' +
            StringParse.rightSpacePad("earlyDevelopment:", LEN)     + earlyDevelopment      + '\n' +
            StringParse.rightSpacePad("helperPackages:", LEN) +
                '[' + StrCSV.toCSV(helperPackages, true, true, null) + ']';
    }


    // ********************************************************************************************
    // ********************************************************************************************
    // Static Helper
    // ********************************************************************************************
    // ********************************************************************************************


    static ReadOnlyList<BuildPackage> nickNameArgVPackages
        (BuildPackage[] allPackages, ReadOnlyList<String> packageNickNames)
    {
        // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
        // Print it to terminal
        // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***

        if (DEBUGGING)
        {
            System.out.print("packageNickNames: ");
            for (String pnn : packageNickNames) System.out.print(pnn + ", ");
            System.out.println();
        }


        // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
        // Pkg Nick-Name Duplicate-Checker (typing the same name more than once - print & exit)
        // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***

        TreeSet<String> duplicateCheckerTS = new TreeSet<>();

        for (String nickName : packageNickNames)

            if (duplicateCheckerTS.contains(nickName))
            {
                System.err.println(
                    "Duplicate Package Nick-Name Provided: " + BRED + nickName + RESET + '\n' +
                    "Exiting..."
                );

                System.exit(1);
            }

            else duplicateCheckerTS.add(nickName);


        // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
        // Convert to a list of "BuildPackage" instances
        // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***    

        // Keeps a list of the packages that matched a nick-name
        ROArrayListBuilder<BuildPackage> roab = new ROArrayListBuilder<>(packageNickNames.size());

        // Keeps a list of any nick-names for which no matching package is found.  This is needed
        // to ensure that if there is one un-matched, that the loop DOES NOT BREAK, and continues
        // to check for matches... So that when there is an unmatched nick-name, the error-message
        // that is ultimately printed to the user - CONTAINS THE LIST OF **ALL** unmatched
        // nick-names.

        Stream.Builder<String> unrecognized = Stream.builder();

        // A flag indicating that there is at least one unmatched package
        boolean atLeastOneMismatch = false;

        TOP:
        for (int i=0; i < packageNickNames.size(); i++)
        {
            for (BuildPackage pkg : allPackages)

                if (pkg.nickName.equals(packageNickNames.get(i)))
                {
                    roab.add(pkg);

                    if (DEBUGGING) System.out.println
                        ("argv[" + i + "]: " + packageNickNames.get(i) + " ==> " + pkg.fullName);

                    continue TOP;
                }

            atLeastOneMismatch = true;
            unrecognized.accept(packageNickNames.get(i));
        }

        if (atLeastOneMismatch)
        {
            System.err.println(
                "Unrecognized Package Nick-Name(s): " +
                "[" +
                BGREEN + String.join(", ", unrecognized.build().toArray(String[]::new)) + RESET +
                "]\n" +
                "This Name could not be mapped to any of your Java Packages to Compile\n" +
                "Exiting...\n"
            );

            System.exit(1);
        }


        // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
        // DONE
        // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***

        return roab.build();
    }
}