package Torello.JavaDoc;

import Torello.HTML.HTMLNode;
import Torello.HTML.SubSection;
import Torello.HTML.Replaceable;
import Torello.HTML.Util;

import Torello.Java.StrPrint;
import static Torello.Java.C.*;

import Torello.JDUInternal.Messager.Messager;
import Torello.JDUInternal.Messager.Where.JDUUserAPI;
import Torello.JDUInternal.Messager.Where.Where_Am_I;

import Torello.JDUInternal.Parse.HTML.HeaderFooter.D1_HeaderFooterRec;

import java.util.Vector;

/**
 * Encapsulates the HTML placed both the top and the bottom of a JavaDoc Web-Page, including the
 * Navigation-Bar HTML, the Package-Name, Type-Signature and other Banner-Labesl.
 * 
 * <EMBED CLASS='external-html' DATA-FILE-ID=PROG_MOD_HTML>
 * <EMBED CLASS='external-html' DATA-FILE-ID=HEADER_FOOTER>
 */
@JDHeaderBackgroundImg(EmbedTagFileID="REFLECTION_HTML_CLASS")
public class HeaderFooterHTML
{
    /** <EMBED CLASS='external-html' DATA-FILE-ID=SVUID> */
    protected static final long serialVersionUID = 1;

    // When the Messager Reports its errors, this class passes this reference to the Messager
    // to facilitate the printing of that information (What class encountered an error or warning
    // that needs to be printed by the Messager).

    private static final Where_Am_I WHERE_AM_I = JDUUserAPI.HeaderFooterHTML;


    // ********************************************************************************************
    // ********************************************************************************************
    // Constructor - Fields are computed in package: Torello.JDUInternal.Parse.HTML.Other
    // ********************************************************************************************
    // ********************************************************************************************


    // This constructor is invoked by JavaDocHTMLFile
    // The work for this constructor has since been moved into a class inside package:
    // 
    // Torello.JDUInternal.Parse.HTML.Other
    // 
    // Keeping HTML-Parsing code in a separate, internal, package allows me to "localize" the
    // complicated parsing code into a single location - far away from the end user.  This code
    // is dependent upon which of the Java-Doc Versions is being used.
    // 
    // Since October of 2024, HTML-Parsing Code has been moved to a single, JDUInternal,
    // suite of directories that are much easier to manage.  This constructor, for instance, just
    // block copies the fields from one of those JDUInternal Data-Record Classes.

    HeaderFooterHTML
        (final Torello.JDUInternal.Parse.HTML.HeaderFooter.D1_HeaderFooterRec internalDataRec)
    {
        this.head               = internalDataRec.head;
        this.topNavBar          = internalDataRec.topNavBar;
        this.packageInfo        = internalDataRec.packageInfo;
        this.title              = internalDataRec.title;
        this.inheritance        = internalDataRec.inheritance;
        this.defListsAboveSig   = internalDataRec.defListsAboveSig;
        this.signature          = internalDataRec.signature;
        this.description        = internalDataRec.description;
        this.defListsBelowDesc  = internalDataRec.defListsBelowDesc;
        this.bottomNavBar       = internalDataRec.bottomNavBar;
    }


    // ********************************************************************************************
    // ********************************************************************************************
    // Private Replaceable-HTML Fields
    // ********************************************************************************************
    // ********************************************************************************************


    private final SubSection head;
    private final SubSection topNavBar;
    private final SubSection packageInfo;
    private final SubSection title;
    private final SubSection inheritance;
    private final Replaceable defListsAboveSig;
    private final SubSection signature;
    private final Replaceable description;
    private final Replaceable defListsBelowDesc;
    private final SubSection bottomNavBar;


    // ********************************************************************************************
    // ********************************************************************************************
    // Public Accessor Methods
    // ********************************************************************************************
    // ********************************************************************************************


    /**
     * Retrieve the HTML {@code <HEAD>}.
     * 
     * @return An HTML-{@code Vector} containing all elements between the opening-{@code <HEAD>}
     * and closing-{@code </HEAD>} tags.  This method shall never return null, nor will it return
     * an empty-{@code Vector}
     */
    public Vector<HTMLNode> head()
    { return this.head.html; }

    /**
     * Retrieve the Navigation-Bar HTML at the top of a Java Doc Page.
     * 
     * @return An HTML-{@code Vector} containing all elements in the Top Navigation-Bar.  If there
     * is no Navigation-Bar at the top, <I>then this method shall return null.</I>
     */
    public Vector<HTMLNode> topNavBar()
    { return (this.topNavBar != null) ? this.topNavBar.html : null; }

    /**
     * Retrieve the Type's Package-Information, as an HTML-{@code Vector}.
     * 
     * @return An HTML-{@code Vector} containing all elements in the package label at the top of a
     * Java-Doc Page.  This method shall never return null, nor will it return an
     * empty-{@code Vector}
     */
    public Vector<HTMLNode> packageInfo()
    { return this.packageInfo.html; }

    /**
     * Retrieve the title of the page, as an HTML-{@code Vector}
     * 
     * @return An HTML-{@code Vector} containing all elements in the title.  This method shall
     * never return null, nor will it return an empty-{@code Vector}
     */
    public Vector<HTMLNode> title()
    { return this.title.html; }

    /**
     * Get the HTML for the Type's inheritance {@code <UL>'s}-List.
     * 
     * @return An HTML-{@code Vector} containing all elements in the Type Inheritance List.  If
     * the Type is an {@code Interface} that does not have any inheriting-types, or an
     * {@code @Annotation}, <I>then this method shall return null.</I>
     */
    public Vector<HTMLNode> inheritance()
    { return (this.inheritance != null) ? this.inheritance.html : null; }

    /**
     * Get any Definition-Lists that occur above the Type's Signature, which is at the top.
     * 
     * @return An HTML-{@code Vector} containing all elements in the definition {@code <DL>} lists
     * below the Yellow-Box Description.  This method shall <I>never return null</I>.  If there are
     * no such lists, then an empty HTML-{@code Vector} is returned.
     * 
     * <BR /><BR />It is perfectly acceptable to add HTML-Content to an empty-list.  Here, it would
     * place such content directly above the Type-Signature {@code <PRE>} box that is located at
     * the top of the page.
     */
    public Vector<HTMLNode> defListsAboveSig()
    { return this.defListsAboveSig.currentNodes(); }

    /**
     * Retrieve the signature HTML from the top of the page.
     * 
     * @return An HTML-{@code Vector} containing all elements in the Type-Signature {@code <PRE>}
     * Element.  This is located at the top of the class, and is box with a shadow border.  This
     * method shall never return null, nor will it return an empty-{@code Vector}
     */
    public Vector<HTMLNode> signature()
    { return this.signature.html; }

    /**
     * Retrieve the description from the top of the page, as HTML.
     * 
     * @return An HTML-{@code Vector} containing all elements in the description, which is a
     * Yellow box at the top of the page.  This method shall <I>never return null</I>.  If there
     * is no such HTML divider, then an empty HTML-{@code Vector} is returned.
     * 
     * <BR /><BR />It is perfectly acceptable to add HTML-Content to an empty-list.  Here, it would
     * place such content directly below the Yellow-Description box that is located at the top of
     * the page.
     */
    public Vector<HTMLNode> description()
    { return this.description.currentNodes(); }

    /**
     * Get any Definition-Lists that occur below the Yellow-Box Signature.
     * 
     * @return An HTML-{@code Vector} containing all elements in the definition {@code <DL>} lists
     * below the Yellow-Box Description.  This method shall <I>never return null</I>.  If there are
     * no such lists, then an empty HTML-{@code Vector} is returned.
     * 
     * <BR /><BR />It is perfectly acceptable to add HTML-Content to an empty-list.  Here, it would
     * place such content directly below the Yellow-Description box that is located at the top of
     * the page.
     */
    public Vector<HTMLNode> defListsBelowDesc()
    { return this.defListsBelowDesc.currentNodes(); }

    /**
     * Retrieve the Navigation-Bar HTML at the bottom of a Java Doc Page.
     * 
     * @return An HTML-{@code Vector} containing all elements in the Bottom Navigation-Bar.  If
     * there is no Navigation-Bar at the top, <I>then this method shall return null.</I>
     */
    public Vector<HTMLNode> bottomNavBar()
    { return (this.bottomNavBar != null) ? this.bottomNavBar.html : null; }


    // ********************************************************************************************
    // ********************************************************************************************
    // DEBUG-PRINTING
    // ********************************************************************************************
    // ********************************************************************************************


    private static final String STARS =
        BYELLOW + "\n*****************************************\n" + RESET;

    /**
     * Prints an abbreviated-version of the contents of this instance, to a user-provided
     * {@code Appendable}.  If the HTML requires more than four lines of text, only the first four
     * lines are printed.
     * 
     * @param a This may be any Java Appendable.  If an {@code IOException} is thrown while writing
     * to this {@code Appendable}, it will be caught an wrapped in an
     * {@code IllegalArgumentException}, with the {@code IOException} set as the {@code cause}.
     * 
     * @throws IllegalArgumentException If {@code 'a'} throws an {@code IOException}
     * @see StrPrint#firstNLines(String, int)
     * @see Util#pageToString(Vector)
     */
    public void debugPrint(Appendable a)
    {
        try 
        {
            a.append(
                STARS + BCYAN + "this.head" + RESET + ':' + STARS +
                StrPrint.firstNLines(Util.pageToString(head.html), 4) +
                '\n'
            );

            if (topNavBar != null) a.append(
                STARS + BCYAN + "this.topNavBar" + RESET + ':' + STARS +
                StrPrint.firstNLines(Util.pageToString(topNavBar.html), 4) +
                '\n'
            );
            else a.append(STARS + BRED + "this.topNavBar is null" + RESET + STARS);

            a.append(
                STARS + BCYAN + "this.packageInfo" + RESET + ':' + STARS +
                StrPrint.firstNLines(Util.pageToString(packageInfo.html), 4) +
                '\n'
            );

            a.append(
                STARS + BCYAN + "this.title" + RESET + ':' + STARS +
                StrPrint.firstNLines(Util.pageToString(title.html), 4) +
                '\n'
            );

            if (inheritance != null) a.append(
                STARS + BCYAN + "this.inheritance" + RESET + ':' + STARS +
                StrPrint.firstNLines(Util.pageToString(inheritance.html), 4) +
                '\n'
            );
            else a.append(STARS + BRED + "this.inheritance is null" + RESET + STARS);

            if (defListsAboveSig.currentSize() > 0) a.append(
                STARS + BCYAN + "this.defListsAboveSig" + RESET + ':' + STARS +
                StrPrint.firstNLines(Util.pageToString(defListsAboveSig.currentNodes()), 4) +
                '\n'
            );
            else a.append(STARS + BRED + "this.defListsAboveSig is empty" + RESET + STARS);

            a.append(
                STARS + BCYAN + "this.signature" + RESET + ':' + STARS +
                StrPrint.firstNLines(Util.pageToString(signature.html), 4) +
                '\n'
            );

            if (description.currentSize() > 0) a.append(
                STARS + BCYAN + "this.description" + RESET + ':' + STARS +
                StrPrint.firstNLines(Util.pageToString(description.currentNodes()), 4) +
                '\n'
            );
            else a.append(STARS + BRED + "this.description is empty" + RESET + STARS);

            if (defListsBelowDesc.currentSize() > 0) a.append(
                STARS + BCYAN + "this.defListsBelowDesc" + RESET + ':' + STARS +
                StrPrint.firstNLines(Util.pageToString(defListsBelowDesc.currentNodes()), 4) +
                '\n'
            );
            else a.append(STARS + BRED + "this.defListsBelowDesc is empty" + RESET + STARS);

            if (bottomNavBar != null) a.append(
                STARS + BCYAN + "this.bottomNavBar" + RESET + ':' + STARS +
                StrPrint.firstNLines(Util.pageToString(bottomNavBar.html), 4) +
                '\n'
            );
            else a.append(STARS + BRED + "this.bottomNavBar is null" + RESET + STARS);
        }
        catch (java.io.IOException ioe)
        {
            throw new IllegalArgumentException(
                "Your Appendable instance has caused an IOException to throw.  See getCause() " +
                "for details", ioe
            );
        }
    }


    // ********************************************************************************************
    // ********************************************************************************************
    // At the end of the processing of a JavaDoc Web-Page, this gets all the changes that were made
    // ********************************************************************************************
    // ********************************************************************************************


    Vector<Replaceable> allReplaceables()
    {
        Vector<Replaceable> ret = new Vector<>();

        ret.add(head);              // Required, always present

        if (topNavBar != null) ret.add(topNavBar);

        ret.add(packageInfo);       // Required, always present
        ret.add(title);             // Required, always present

        if (inheritance != null) ret.add(inheritance);

        ret.add(defListsAboveSig);  // A "Replaceable" is never null.
        ret.add(signature);         // Required, always present
        ret.add(description);       // A "Replaceable" is never null.
        ret.add(defListsBelowDesc); // A "Replaceable" is never null.

        if (bottomNavBar != null) ret.add(bottomNavBar);

        return ret;
    }


    // ********************************************************************************************
    // ********************************************************************************************
    // THE NEW-THING: Garbage-Collector Helper?
    // ********************************************************************************************
    // ********************************************************************************************
    // 
    // Does this help?  Is this "good" for the Garbage-Collect?  Is this going to speed it up,
    // or slow it down?  This is just a "C-Styled" FREE or DESTORY method...
    // It isn't publicly visible anyway...

    void clear()
    {
        // private final SubSection head;
        // Guaranteed: Never Null, or Messager.assertFailHTML

        head.html.clear();
        head.html = null;

        // private final SubSection topNavBar;
        // Maybe they don't have one

        if (topNavBar != null)
        {
            topNavBar.html.clear();
            topNavBar.html = null;
        }

        // private final SubSection packageInfo;
        // Guaranteed: Never Null, or Messager.assertFailHTML
        // NOTE: This may one day change...

        if (packageInfo != null)
        {
            packageInfo.html.clear();
            packageInfo.html = null;
        }

        // private final SubSection title;
        // Guaranteed: Never Null, or Messager.assertFailHTML

        title.html.clear();
        title.html = null;

        // private final SubSection inheritance;
        // Maybe they don't have one

        if (inheritance != null)
        {
            inheritance.html.clear();
            inheritance.html = null;
        }

        // private final Replaceable defListsAboveSig;
        // THIS IS A REPLACEABLE: It won't be null, but it may be empty

        if (SubSection.class.isAssignableFrom(defListsAboveSig.getClass()))
        {
            ((SubSection) defListsAboveSig).html.clear();
            ((SubSection) defListsAboveSig).html = null;
        }
        else if (defListsAboveSig.currentSize() > 0) defListsAboveSig.clearHTML();

        // private final SubSection signature;
        // Guaranteed: Never Null, or Messager.assertFailHTML

        signature.html.clear();
        signature.html = null;

        // private final Replaceable description;
        // THIS IS A REPLACEABLE: It won't be null, but it may be empty

        if (SubSection.class.isAssignableFrom(description.getClass()))
        {
            ((SubSection) description).html.clear();
            ((SubSection) description).html = null;
        }
        else if (description.currentSize() > 0) description.clearHTML();

        // private final Replaceable defListsBelowDesc;
        // THIS IS A REPLACEABLE: It won't be null, but it may be empty

        if (SubSection.class.isAssignableFrom(defListsBelowDesc.getClass()))
        {
            ((SubSection) defListsBelowDesc).html.clear();
            ((SubSection) defListsBelowDesc).html = null;
        }
        else if (defListsBelowDesc.currentSize() > 0) defListsBelowDesc.clearHTML();

        // private final SubSection bottomNavBar;
        // Maybe they don't have one

        if (bottomNavBar != null)
        {
            bottomNavBar.html.clear();
            bottomNavBar.html = null;
        }
    }
}