B1_PackageSummaryHTML.java.html

package Torello.JDUInternal.Parse.HTML.PkgSummary;

import static Torello.Java.C.*;

import Torello.HTML.*;
import Torello.HTML.NodeSearch.*;

import Torello.Java.FileRW;

import Torello.Java.Additional.Ret2;

import Torello.JDUInternal.Messager.Messager;
import Torello.JDUInternal.Messager.MsgControl;
import Torello.JDUInternal.Messager.Where.JDUParse;
import Torello.JDUInternal.Messager.Where.Where_Am_I;

import java.io.File;
import java.io.IOException;

import java.util.*;

import java.util.function.Consumer;

public class B1_PackageSummaryHTML
{
    // This is used to help with the Header-Tags invocation.
    public static class FriendClass { private FriendClass() {} }
    private static final FriendClass FRIEND_ACCESS = new FriendClass();

    private static final Where_Am_I WHERE_AM_I = JDUParse.PkgSummary.asSubSection(
        B1_PackageSummaryHTML.class,
        "Record used for extacting and storing all information about a 'package-summary.html' file"
    );


    // ********************************************************************************************
    // ********************************************************************************************
    // Static-Final Constant Fields
    // ********************************************************************************************
    // ********************************************************************************************


    private static final Vector<HTMLNode> TABLE_START = HTMLPage.getPageTokens(
        "<UL CLASS=blockList>\n" +
        "<LI CLASS=blockList>\n" +
        "<TABLE CLASS=typeSummary BORDER=0 CELLPADDING=3 CELLSPACING=0 " +
        "summary=\"Summary table, listing Classes, Interfaces and Enums, etc...\">\n",
        false
    );

    private static final Vector<HTMLNode> TABLE_END =
        HTMLPage.getPageTokens("</UL>\n</LI>\n</TABLE>\n", false);

    private static final char FSEP = File.separator.charAt(0);

    private static final String PKG_SUMM_HTML = "Package Summary HTML";

    private static final TagNode BODY_WITH_CSS_CLASS_TN = new TagNode("<BODY CLASS=C30>");


    // ********************************************************************************************
    // ********************************************************************************************
    // This class Main-Builder (Constructor)
    // ********************************************************************************************
    // ********************************************************************************************


    public static Torello.JavaDoc.PackageSummaryHTML build(
            // The 'package-summary.html' file has actually already been parsed into a
            // Vector<HTMLNode>.  This is a (very small) Data-Record that stores the HTML-Vector
            // and the actual, Complete File-Name for both:
            // 
            //      * 'package-frame.html'
            //      * 'package-summary.html'
            // 
            // public class D1_PkgFrameAndSummFiles 
            //      public final Vector<HTMLNode> pkgSummaryHTMLFile;
            //      public final String pkgSummaryHTMLFileName;
            //      public final String pkgFrameHTMLFileName;

            final Torello.JDUInternal.MainJDU.Preliminary.D1_PkgFrameAndSummFiles
                parsedPkgSummaryFile,

            final String packageName,
    
            final Torello.JDUInternal.MainJDU.ClassUpgradeData.UpgradeSettings settings,

            // The Relative-Path Information to the Root Java-Doc Directory
            final Torello.JavaDoc.RelativePathStr dotDots,


            // This is now, officially, stored inside of the "Total Package Data-Record"
            //  * a.k.a.: 'aufd'
            //  * a.k.a.: D1_AllUpgradeFilesData
            // 
            // The sorter for this thing.  This was already loaded from disk
            // final Torello.JDUInternal.Features.SORT_TYPES_FRAMES_SUMMARIES.D1_PkgSort
            // 
            // THIS **IS NOT** RETAINED - HOWEVER IT **IS USED**
            // 
            // This is used to do the sorting.  It is not retained.  It is retained inside of
            // 'aufd' - a.k.a.  'D1_AllUpgradeFilesData'

            final Torello.JDUInternal.Features.SORT_TYPES_FRAMES_SUMMARIES.D1_PkgSort
               frameSummSorter
        )
    {
        MsgControl.setCurrentFileName
            (parsedPkgSummaryFile.pkgSummaryHTMLFileName, "'package-summary.html' File");

        final Consumer<Vector<HTMLNode>> packageSummaryCleaner = settings.packageSummaryCleaner;

        Vector<HTMLNode> fileVec = parsedPkgSummaryFile.pkgSummaryHTMLFileVec;


        // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
        // The Fields that need to be initialized
        // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***

        final SubSection head;
        final SubSection topNavBar;
        final SubSection bottomNavBar;
        final SubSection description;


        // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
        // Sort **OR** just Clean-Up the CIET/Type List on this web-page
        // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***

        // The rows (which contain CIET/Types) of this 'package-summary.html' File
        Vector<Vector<HTMLNode>>    cietRowHTML;
        Vector<String>              cietRowSimpleNames;

        final Ret2 <Vector<String>, Vector<Vector<HTMLNode>>> r2;

        if (frameSummSorter != null)
        {
            // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
            // Read the File's Contents & Sort if needed.
            // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***

            // Builds a TreeMap of all of the table rows on the "Package Summary" JavaDoc HTML Page
            HNLIInclusive iter = S1_A_ExtractRows_ExceptTitleRows.iter(fileVec);


            // Save the rows by CIET-Name in a TreeMap
            // Map-Key:     CIET Simple-Name
            // Map-Value:   Table-Row of HTML <TR> ... </TR>

            final TreeMap<String, Vector<HTMLNode>> entries = new TreeMap<>();


            // Fill the TreeMap with all of the table-rows on the page.  These are going to be
            // completely rearranged in the next step.

            while (iter.hasNext())
            {
                Vector<HTMLNode>    cietHTML        = iter.next();
                int                 pos             = TagNodeFind.first(cietHTML, TC.OpeningTags, "a");
                String              cietSimpleName  = cietHTML.elementAt(pos + 1).str;

                entries.put(cietSimpleName, cietHTML); // Saved for Sorting
            }

            r2 = Torello.JDUInternal.Features.SORT_TYPES_FRAMES_SUMMARIES.S2_Rearrange
                .API_RearrangePkgSummaryFile.rearrange
                    (frameSummSorter.pkgSummarySectionTitles, frameSummSorter.types, entries);


            // If there were errors, then the above function might return null.  Halt the
            // constructor here, BUT do not throw so that all of the PackageSummaryHTML's can
            // execute, FIRST, before quitting.

            if (r2 == null)
            {
                // Prevent `javac` complaints: (final field may not have been initialized)
                cietRowHTML         = null;
                cietRowSimpleNames  = null;


                // These are all SubSection instances
                // *** INITIALZE THE VARS FOR THE 'PackageSummaryHTML' Constructor

                head = topNavBar = bottomNavBar = description = null;

                return null;
            };
        }


        // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
        // Read the File's Contents & Clean-It
        // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***

        else r2 = Torello.JDUInternal.Parse.HTML.PkgSummary.S1_B_ExtractRows.run(fileVec);

        cietRowSimpleNames  = r2.a;
        cietRowHTML         = r2.b;


        // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
        // Build the Updated 'package-summary.html' Page
        // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***

        // This DotPair contains the entire Summary-Table in a package-summary.html file
        DotPair dp = InnerTagFindInclusive.first
            (fileVec, "ul", "class", TextComparitor.C, "blockList");

        // Build the new Package-Summary CIET/Type Table
        final Vector<HTMLNode> newTable = new Vector<>();

        newTable.addAll(TABLE_START);

        for (Vector<HTMLNode> cietHTML : cietRowHTML) newTable.addAll(cietHTML);

        newTable.addAll(TABLE_END);

        // Insert the new Table into the same location where the old table had been placed
        ReplaceNodes.r(fileVec, dp, newTable);


        // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
        // Check if there is a User-Provided (or Default) "Package Summary Cleaner"
        // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***

        // MESSAGER: Messager.isVerbose, println only
        if (packageSummaryCleaner != null)
            Torello.JDUInternal.Features.SORT_TYPES_FRAMES_SUMMARIES
                .H1_Reorder_SummClean_.run(fileVec, packageSummaryCleaner);

        // Hi-Lite any User-Provided <DIV CLASS=xxx>{@code blocks inside the Package-Summary
        Torello.JDUInternal.SimpleFeatures.HiLiteDividers
            .hiLite(fileVec, settings.hiLiter);


        // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
        // Retrieve the <HEAD>...</HEAD> Header
        // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
        // 
        // *** INITIALZE THE VARS FOR THE 'PackageSummaryHTML' Constructor
        head = TagNodePeekInclusive.first(fileVec, "head");

        if (head == null) Messager.assertFailHTML(
            "This 'package-summary.html' page does not appear to have a <HEAD>...</HEAD> Element",
            PKG_SUMM_HTML,
            WHERE_AM_I
        );


        // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
        // The Top Navigation-Bar - There may be pages which do not have a NavBar
        // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
        //
        // NOTE: I just noticed that the Navigation-Bar is a series of <DIV>'s, and there is no
        //       surrounding HTML divider.  We have to find the first open-<DIV>, and the last
        //       closing </DIV>

        int sPos = CommentNodeFind.first
            (fileVec, head.location.end, -1, s -> s.contains("=== START OF TOP NAVBAR ==="));

        int ePos;

        if (sPos == -1)
        {
            // *** INITIALZE THE VARS FOR THE 'PackageSummaryHTML' Constructor
            topNavBar = null;
            ePos = head.location.end;
        }

        else
        {
            ePos = CommentNodeFind.first
                (fileVec, sPos, -1, s -> s.contains("=== END OF TOP NAVBAR ==="));

            sPos = TagNodeFind.first(fileVec, sPos, ePos, TC.OpeningTags, "div");
            ePos = TagNodeFind.last(fileVec, sPos, ePos, TC.ClosingTags, "div");

            dp = new DotPair(sPos, ePos);

            // *** INITIALZE THE VARS FOR THE 'PackageSummaryHTML' Constructor
            topNavBar = new SubSection(dp, Util.cloneRange(fileVec, dp));
        }


        // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
        // Package-Description
        // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
        //
        // *** INITIALZE THE VARS FOR THE 'PackageSummaryHTML' Constructor

        description = TagNodePeekInclusive.first(fileVec, ePos, -1, "section");

        if (description == null) Messager.assertFailHTML(
            "This Package returned a null Description.\n" +
            "This occurs when no 'package-info.java' File was created for the Package you are " +
                "attempting to Upgrade.\n" +
            "Please define some kind of 'package-info.java' file for package:\n\t" +
            BYELLOW + packageName + RESET,
            PKG_SUMM_HTML, WHERE_AM_I
        );


        // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
        // The Bottom Navigation-Bar, There may be pages which do not have a NavBar
        // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
        //
        // Searching through "CommentNode" instances is much faster since the
        // if (HTMLNode.isCommentNode()) is the fastest of the search-specifies...  There aren't
        // many comment's in a javadc page (much fewer than the number of TagNode's & TextNode's)
        //
        // ALSO: as explained in the "Top Navigation-Bar" getter-section (way above this part),
        //       The Bottom and Top Bar's are a series of "sibling" <DIV> Tags, and you have to
        //       get the first opening-<DIV> and the last closing-</DIV>

        sPos = CommentNodeFind.first(fileVec, s -> s.contains("== START OF BOTTOM NAVBAR =="));


        // *** INITIALZE THE VARS FOR THE 'PackageSummaryHTML' Constructor
        if (sPos == -1) bottomNavBar = null;

        else
        {
            ePos = CommentNodeFind.first
                (fileVec, sPos, -1, s -> s.contains("=== END OF BOTTOM NAVBAR ==="));

            if (ePos == -1)
                Messager.assertFailHTML("BOTTOM NAVBAR End-Marker not found", null, WHERE_AM_I);

            sPos = TagNodeFind.first(fileVec, sPos, ePos, TC.OpeningTags, "div");
            ePos = TagNodeFind.last(fileVec, sPos, ePos, TC.ClosingTags, "div");
    
            dp = new DotPair(sPos, ePos);


            // *** INITIALZE THE VARS FOR THE 'PackageSummaryHTML' Constructor
            bottomNavBar = new SubSection(dp, Util.cloneRange(fileVec, dp));
        }


        // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
        // Meta-Tags in Header, Stats Button in Navigation Bar
        // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
        // 
        // The Tags which are used inside of a 'package-summary.html' file are, tenatively, just 
        // going to be the **SAME EXACT** tags which are used inside of all of the Primary Java-Doc
        // Web-Page Files.    Thusly, here the class 'MainJavaFileTags' is used.

        final List<HTMLNode> tags = Torello.JDUInternal.Miscellaneous.HeaderMetaTags
            .MainJavaFileTags.get(
                ((settings.cssFiles == null) ? null : settings.cssFiles.customizedCSS),
                dotDots.urls,
                settings.faviconImageFileName,
                settings.headerTags,
                FRIEND_ACCESS
            )
            .wrapToImmutableList();

        // *** INITIALZE THE VARS FOR THE 'PackageSummaryHTML' Constructor
        head.html.addAll(1, tags);

        Torello.JDUInternal.Features.STATS.API_Stats.addStatsButton(
            (topNavBar == null)     ? null : topNavBar.html,
            (bottomNavBar == null)  ? null : bottomNavBar.html,
            dotDots.urls,
            packageName
        );


        // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
        // Re-Build the Page-Vector
        // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***

        Replaceable[] replaceables =
            { head, topNavBar, description, bottomNavBar };

        fileVec = Replacement.run(fileVec, Arrays.asList(replaceables), false).a;


        // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
        // Write the new 'package-summary.html' to Disk
        // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***

        try
        {
            FileRW.writeFile
                (Util.pageToString(fileVec), parsedPkgSummaryFile.pkgSummaryHTMLFileName);
        }

        catch (IOException ioe)
        {
            Messager.assertFailGeneralPurpose
                (ioe, "Failed Writing 'package-summary.html' File", null, WHERE_AM_I);
        }


        // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
        // Handle 'package-frame.html' - IF IT EXISTS
        // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
        //
        // Requirements:
        // 1) User has provided a Package-Sorter
        // 2) JavaDoc has created a package-frame.html file

        // Now check that the package-frame.html file exists, and is an HTML-File
        if (parsedPkgSummaryFile.pkgFrameFileExists)
        {
            MsgControl.setCurrentFileName
                (parsedPkgSummaryFile.pkgFrameHTMLFileName, "'package-frame.html' File");

            // Read the file from disk and parse into Vectorized-HTML
            fileVec =
                Torello.JDUInternal.Miscellaneous.ReadFile.loadHTMLFile
                    (parsedPkgSummaryFile.pkgFrameHTMLFileName, "package-frame.html", WHERE_AM_I);


            // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
            // Rearrange 'package-frame.html'
            // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***

            if (frameSummSorter != null)

                Torello.JDUInternal.Features.SORT_TYPES_FRAMES_SUMMARIES.S2_Rearrange
                    .API_RearrangePkgFrameFile.rearrange
                        (fileVec, frameSummSorter.pkgFrameSectionTitles, frameSummSorter.types);


            // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
            // Original "Package-Frame Cleaner" - Moved Here from EFP, November 2023
            // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***

            fileVec.setElementAt(
                BODY_WITH_CSS_CLASS_TN,     /* <BODY CLASS=C30> */
                TagNodeFind.first(fileVec, TC.OpeningTags, "body")
            );

            /*
            // February 2024, EVEN-BETTER
            // Just do <BODY CLASS=C30> inside of a 'package-frame.html' file INSTEAD OF ALL OF
            // THESE STUPID "extra CSS Classses"
            // SEE ABOVE 3 LOC

            for (TagNodeIndex tni : TagNodePeek.all(filfileVeceVec, TC.OpeningTags, "h1", "h2", "ul"))

                if (tni.n.tok.equals("h1"))            
                    fileVec.setElementAt(
                        tni.n.appendCSSClass(CSSTags.CSS_CLASS_FOR_PKG_FRAME_H1, null),
                        tni.index
                    );

                else if (tni.n.tok.equals("h2"))
                    fileVec.setElementAt(
                        tni.n.appendCSSClass(CSSTags.CSS_CLASS_FOR_PKG_FRAME_H2, null),
                        tni.index
                    );

                else // if (tni.n.tok.equals("ul"))
                    fileVec.setElementAt(
                        tni.n.appendCSSClass(CSSTags.CSS_CLASS_FOR_PKG_FRAME_UL, null),
                        tni.index
                    );
            */


            // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
            // Meta-Tags in Header
            // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***

            final int pkgFrameHeaderPos = TagNodeFind.first(fileVec, TC.OpeningTags, "HEAD");

            fileVec.addAll(pkgFrameHeaderPos + 1, tags);


            // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
            // Write 'package-frame.html' back to disk
            // *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***

            try
            {
                FileRW.writeFile(
                    Util.pageToString(fileVec),
                    parsedPkgSummaryFile.pkgFrameHTMLFileName
                );
            }

            catch (IOException ioe)
            {
                Messager.assertFailGeneralPurpose
                    (ioe, "Failed Writing 'package-summary.html' File", null, WHERE_AM_I);
            }
        }

        return new Torello.JavaDoc.PackageSummaryHTML
            (packageName, head, topNavBar, bottomNavBar, description);
    }

}