package Torello.HTML;

import java.util.Vector;
import java.util.NoSuchElementException;

import Torello.Java.UnreachableError;
import Torello.HTML.NodeSearch.*; // Used for JavaDoc Comment Links

/**
 * The class {@link ReplaceNodes} offers a great <B><I>efficiency-improvement</I></B> optimization
 * for modifying vectorized-HTML.  HTML Pages can be very long, and the insertion or removal of a
 * piece or snippet of HMTL may result in the shifting of hundreds (or even thousands!) of
 * {@code HTMLNode's}.  This can incur a non-trivial performance cost if many there are many
 * updates and changes to be made to a page.
 * 
 * <BR /><BR /><HR><BR />
 * 
 * <B CLASS=JDDescLabel>Exceprt from {@link #currentNodes()}:</B>
 * 
 * <BR />{@code Replaceable's} are, sort-of, <B STYLE='color: red'>the exact opposite</B> of Java's
 * {@code List} method {@code 'subList'}.  According to the Sun / Oracle Documentation for
 * {@code java.util.List.subList(int fromIndex, int toIndex)}, any changes ffinamade to an instance of a
 * {@code 'subList'} are immediately reflected back into the original {@code List} from where they
 * were created.
 * 
 * <BR /><BR />The {@code List.subList} operation has the advantage of being extremely easy to
 * work with - however, an HTML-Page {@code Vector} has the potential of being hundreds of
 * nodes long.  Any operations that involve insertion or deletion will likely be terribly
 * inefficient. 
 * 
 * <BR /><BR /><B STYLE='color: red'><I>When the HTML inside of a {@code Replaceable} is
 * modified - nothing happens to the original {@code Vector} whatsoever!</I></B>.  Until a user
 * requests that the original HTML-{@code Vector} be updated to reflect all changes that he or 
 * she has made, the original HTML remains untouched.  When an update request is finally
 * issued, all changes are made all at once, and at the same time!
 * 
 * <BR /><BR />Again - see {@link ReplaceNodes#r(Vector, Iterable, boolean)} to understand
 * how quick updates on HTML-Pages is done using the {@code Replaceable} interface.
 * 
 * <BR /><BR /><HR><BR />
 * 
 * <B CLASS=JDDescLabel>Utilizing class {@link ReplaceNodes}:</B>
 * 
 * <BR />Class {@link ReplaceNodes} offers three methods for performing these optimized replacement
 * methods.  These methods are listed below.  The optimization that is utilized there is to first
 * calculate the size / length of the updated {@code Vector}, and then do the entire update all at
 * once.  This eliminates to do any shifting and only performs a single resizing of the
 * {@code Vector}.
 * 
 * <BR /><BR />These methods will work in lock-step with interface {@code 'Replaceable'} to
 * actually perform the update after all Vectorized-HTML has been changed, sufficiently as deemed
 * by the programmer:
 * 
 * <BR /><BR /><UL CLASS=JDUL>
 *      <LI><B>{@link ReplaceNodes#r(Vector, Iterable, boolean)}</B></LI>
 *      <LI><B>{@link ReplaceNodes#listLI(Vector, DotPair, ObjIntConsumer)}</B></LI>
 *      <LI><B>{@link ReplaceNodes#tableTR(Vector, DotPair, ObjIntConsumer)}</B></LI>
 * </UL>
 * 
 * <BR /><BR />The Java Doc Upgrader Tool in this JAR Library heavily relies on using instances of
 * {@code Replaceable} to update and modify Java Doc HTML in a fast, simple &amp; efficient manner.
 * 
 * <BR /><BR />Though this class may look somewhat complicated to understand, in all reality it is
 * actually very simple.  Load a web-page from disk (or download one from the Internet) and run it
 * through the parser (class {@link HTMLPage}) to make a Vectorized-HTML Page.  Next, build a few
 * instances of {@link SubSection} which hold <B><I>both</I></B> the location of an HTML snippet
 * <B><I>and</I></B> HTML itself.
 * 
 * <BR /><Br />Finallly, make whatever modifications you want to those HTML snippets, and call the
 * <B>{@code ReplaceNodes}</B> method listed first in the list above!  The page should be updated
 * quickly with little cost overhead.
 * 
 * <BR /><BR /><HR><BR />
 * 
 * <B CLASS=JDDescLabel>Peek Operation Replaceables</B>
 * 
 * <BR />The class {@link InnerTagPeekInclusive} and {@link TagNodePeekInclusive} will always
 * generate properly ordered / sorted <B STYLE='color: red;'><I>references that implement the
 * {@code Replaceable} interface!</I></B>  Furthermore, these instances will be ones that are 
 * sorted and do not overlap.
 * 
 * <BR /><BR />This means that if a set or collection of {@code Replaceable's} were created using
 * the {@code NodeSearch 'Peek'} Search-Classes, the
 * {@link ReplaceNodes#r(Vector, Iterable, boolean)} requirements that the {@code Replaceable's} be
 * ordered, sorted and non-overlapping would be automatically met.
 * 
 * <BR /><BR />This interface is implemented by all return-values for the {@code NodeSearch} <B>Peek</B>
 * operations.
 * 
 * <BR /><BR /><UL CLASS=JDUL>
 * <LI>{@link TextNodePeek}</LI>
 * <LI>{@link CommentNodePeek}</LI>
 * <LI>{@link TagNodePeek}</LI>
 * <LI>{@link TagNodePeekInclusive}</LI>
 * <LI>{@link InnerTagPeek}</LI>
 * <LI>{@link InnerTagPeekInclusive}</LI>
 * </UL>
 */
public interface Replaceable extends Comparable<Replaceable>
{
    // ********************************************************************************************
    // ********************************************************************************************
    // basic interface stuff
    // ********************************************************************************************
    // ********************************************************************************************


    /**
     * Java's {@code Comparable} interface requirements.
     * 
     * @return An integer based on comparing the starting locations for two {@code Replaceable}
     * instances.
     */
    public default int compareTo(Replaceable other)
    { return this.originalLocationStart() - other.originalLocationStart(); }

    /**
     * Supplies a hash-code
     * 
     * @return The value returned by {@link #originalLocationStart()}, which must be unique among
     * any list of {@code Replaceable's}.
     */
    // It say this isn't allowed
    // public default int hashCode()
    // { return originalLocationStart(); }


    // ********************************************************************************************
    // ********************************************************************************************
    // The 'addAll' - used by class ReplaceNodes
    // ********************************************************************************************
    // ********************************************************************************************


    /** 
     * Reports how many nodes were copied into {@code this} instance.
     * For implementing classes that inherit {@link NodeIndex}, this value will always be one.
     * For others, it should report exactly how many {@code HTMLNode's} were copied.
     * 
     * @return Number of nodes originally contained by {@code this} instance.
     * 
     * <A ID=NOTE1> <!-- NOTE --> </A>
     * 
     * <BR /><BR />The purpose of {@code Replaceable's} is to allow a user to modify HTML using
     * a smaller sub-list, without having to operate on the entire HTML-{@code Vector} since adding
     * &amp; removing nodes is one variant of {@code Vector}-modification, the <I>original-size</I>
     * may often differ from the <I>current-size</I>.
     * 
     * <BR /><BR />When modifying HTML, if a web-page is broken into smaller-pieces, and changes
     * are restricted to those smaller sub-lists (and the original page is rebuilt, <I>all at
     * once</I>, after all changes have been made) then those modifications should require far-fewer
     * time-consuming list-shift operations, tremendously improving the performance of the code.
     */
    public int originalSize();

    /**
     * Returns how many nodes are currently in {@code this} instance.
     * 
     * @return Number of nodes.  See explanation of the <B STYLE='color: red;'>original</B> size,
     * versus the <B STYLE='color: red;'>current</B> size
     * <B><CODE><A HREF='#NOTE1'>here</A></CODE></B>
     */
    public int currentSize();

    /**
     * Returns the <B STYLE='color: red;'>start</B>-location within the original
     * page-{@code Vector} from whence the HTML contents of {@code this} instance were retrieved.
     * 
     * <BR /><BR /><B CLASS=JDDescLabel>Start is Inclusive:</B>
     * 
     * <BR />The returned value is <B STYLE='color: red;'><I>inclusive</I></B> of the actual,
     * original-range of {@code this} instance.  This means the first {@code HTMLNode} copied into
     * {@code this} instance' internal data-structure was at {@code originalLocationStart()}.
     * 
     * <BR /><BR /><B CLASS=JDDescLabel>Implementations of Replaceable:</B>
     * 
     * <BR />The two concrete implementatons of this interface ({@link NodeIndex} and
     * {@link SubSection}) - both enforce the {@code 'final'} modifier on their location-fields.
     * (See: {@link NodeIndex#index} and {@link SubSection#location}).
     * 
     * @return The {@code Vector} <B STYLE='color: red;'>start</B>-index from whence this HTML was
     * copied.
     */
    public int originalLocationStart();

    /**
     * Returns the <B STYLE='color: red;'>end</B>-location within the original
     * page-{@code Vector} from whence the HTML contents of {@code this} instance were retrieved.
     * 
     * <BR /><BR /><B CLASS=JDDescLabel>Start is Exclusive:</B>
     * 
     * <BR />The returned value is <B STYLE='color: red;'><I>exclusive</I></B> of the actual,
     * original-range of {@code this} instance.  This means the last {@code HTMLNode} copied into
     * {@code this} instance' internal data-structure was at {@code originalLocationEnd() - 1}
     * 
     * <BR /><BR /><B CLASS=JDDescLabel>Implementations of Replaceable:</B>
     * 
     * <BR />The two concrete implementatons of this interface ({@link NodeIndex} and
     * {@link SubSection}) - both enforce the {@code 'final'} modifier on their location-fields.
     * (See: {@link NodeIndex#index} and {@link SubSection#location}).
     * 
     * @return The {@code Vector} <B STYLE='color: red;'>end</B>-index from whence this HTML was
     * copied.
     */
    public int originalLocationEnd();


    /**
     * All nodes currently contained by this {@code Replaceable}.  The concrete-classes which
     * implement {@code Replaceable} ({@link SubSection} &amp; {@link TagNodeIndex}) allow for the
     * html they hold to be modified.  The modification to a {@code Replaceable} happens
     * independently from the original HTML Page out of which it was copied.
     * 
     * <BR /><BR />{@code Replaceable's} are, sort-of, <B STYLE='color: red'>the exact opposite</B>
     * of Java's {@code List} method {@code 'subList'}.  According to the Sun / Oracle
     * Documentation for {@code java.util.List.subList(int fromIndex, int toIndex)}, any changes
     * made to an instance of a {@code 'subList'} are immediately reflected back into the original
     * {@code List} from where they were created.
     * 
     * <BR /><BR />The {@code List.subList} operation has the advantage of being extremely easy to
     * work with - however, an HTML-Page {@code Vector} has the potential of being hundreds of
     * nodes long.  Any operations that involve insertion or deletion will likely be terribly
     * inefficient. 
     * 
     * <BR /><BR /><B STYLE='color: red'><I>When the HTML inside of a {@code Replaceable} is
     * modified - nothing happens to the original {@code Vector} whatsoever!</I></B>.  Until a user
     * requests that the original HTML-{@code Vector} be updated to reflect all changes that he or 
     * she has made, the original HTML remains untouched.  When an update request is finally
     * issued, all changes are made all at once, and at the same time!
     * 
     * <BR /><BR />Again - see {@link ReplaceNodes#r(Vector, Iterable, boolean)} to understand
     * how quick updates on HTML-Pages is done using the {@code Replaceable} interface.
     * 
     * @return An HTML-{@code Vector} of the nodes.
     */
    public Vector<HTMLNode> currentNodes();

    /**
     * The first node <B STYLE='color: red;'>currently</B> contained by this {@code Replaceable}
     * @return The First Node
     */
    public HTMLNode firstCurrentNode();

    /**
     * The last node <B STYLE='color: red;'>currently</B> contained by this {@code Replaceable}
     * @return The last node
     */
    public HTMLNode lastCurrentNode();


    // ********************************************************************************************
    // ********************************************************************************************
    // The 'addAll' - used by class ReplaceNodes
    // ********************************************************************************************
    // ********************************************************************************************


    /**
     * Add all nodes currently retained in {@code this} instance into the HTML-{@code Vector}
     * parameter {@code html}.  The nodes are appended to the end of {@code 'html'}.  Implementing
     * classes {@link NodeIndex} and {@link SubSection} simply use the Java {@code Vector} method's
     * {@code add} (for {@code NodeIndex}) and {@code addAll} (for {@code SubSection}).
     * 
     * @param html The HTML-{@code Vector} into which the nodes will be appended (to the end of
     * this {@code Vector}, using {@code Vector} methods {@code add} or {@code addAll} dependent
     * upon whether one or more-than-one nodes are being inserted).
     * 
     * @return The result of {@code Vector} method {@code add}, or method {@code allAll}
     */
    public boolean addAllInto(Vector<HTMLNode> html);

    /**
     * Add all nodes currently retained in {@code this} instance into the HTML-{@code Vector}
     * parameter {@code html}.
     * 
     * @param index The {@code 'html'} parameter's {@code Vector}-index where these nodes are to
     * be inserted
     * 
     * @param html The HTML-{@code Vector} into which the nodes will be appended (to the end of
     * this {@code Vector}, using {@code Vector} methods {@code add} or {@code addAll} dependent
     * upon whether one or more-than-one nodes are being inserted).
     * 
     * @return The result of {@code Vector} method {@code add}, or method {@code allAll}
     */
    public boolean addAllInto(int index, Vector<HTMLNode> html);


    // ********************************************************************************************
    // ********************************************************************************************
    // update - inefficient, unless only used for a single page-update
    // ********************************************************************************************
    // ********************************************************************************************


    /**
     * <EMBED CLASS='external-html' DATA-FILE-ID=REPL_UPDATE_DESC>
     * 
     * @param originalHTML The original page-{@code Vector} where the nodes in {@code this}
     * instance were retrieved
     * 
     * @return The change in the size of the {@code Vector}
     * 
     * @see ReplaceNodes#r(Vector, Iterable, boolean)
     * 
     * @throws IndexOutOfBoundsException If {@link #originalLocationStart()} or 
     * {@link #originalLocationEnd()} are not within the bounds of the input html-page.
     */
    public int update(Vector<HTMLNode> originalHTML);


    // ********************************************************************************************
    // ********************************************************************************************
    // Building New Instance: Change the HTML of a Replaceable, **WITHOUT USING SUB-CLASS' FIELDS**
    // ********************************************************************************************
    // ********************************************************************************************


    /**
     * This method may be used for arbitrary replacements.  An instance of {@code NodeIndex}
     * (one of its sub-classes) only contains a single {@code HTMLNode}.  To change that to a list,
     * or to remove that node altogether, invoke this method, and a new instance of
     * {@code Replaceable} will be automatically created, and returned.
     * 
     * <BR /><BR />This may be a little tricky at first, but the primary reason for using this
     * method is that size-changes that would make a <B STYLE='color: red;'>single-node</B>
     * ({@link NodeIndex} instance) into a <B STYLE='color: red;'>list</B> ({@link SubSection}
     * instance), or vice-versa, would require building a different type of {@code Replaceable}
     * instance.  This method will automatically build that instance into a {@code Replaceable}
     * that retains its <I>original location</I>, but reflects its <I>new contents and size</I>.
     * 
     * <BR /><BR />Once again, the primary impetus for this method is using it with an in-place
     * page update having multiple-replacements, <I>vis-a-vis</I> a call to
     * {@link ReplaceNodes#r(Vector, Iterable, boolean)}.
     * 
     * @param newHTML The contents of {@code 'this'} replaceable will be assigned to the the html
     * in this parameter.
     * 
     * @return a new replaceable whose <I><B STYLE='color: red;'>location</B> has not changed</I>,
     * but whose contents are the contents of {@code newHTML}.
     */
    public default Replaceable setHTML(Vector<HTMLNode> newHTML)
    {
        final int oldSize   = this.originalSize();
        final int newSize   = newHTML.size();
        final int sPos      = this.originalLocationStart();
        final int ePos      = this.originalLocationEnd();

        // SubSection ==> SubSection
        if ((oldSize > 1) && (newSize > 1))
            return new SubSection(new DotPair(sPos, ePos - 1), newHTML);

        // NodeIndex ==> NodeIndex
        if ((oldSize == 1) && (newSize == 1))
            return NodeIndex.newNodeIndex(sPos, newHTML.elementAt(0));

        // Empty ==> Empty
        if ((oldSize == 0) && (newSize == 0))
            return empty(sPos);

        return new ReplaceableAdapter(sPos, ePos, newHTML);
    }

    /**
     * See the description in {@link #setHTML(Vector)} to understand when to use {@code setHTML}.
     * This method is identical, but accepts a single {@link HTMLNode} instance, instead of an html
     * list.
     * 
     * @param newHTML The contents of {@code 'this'} replaceable will be assigned to the the html
     * contained by {@code newHTML}.  (The returned instance will have the same location values)
     * 
     * @return a new replaceable whose <I><B STYLE='color: red;'>location</B> has not changed</I>,
     * but whose contents are {@code newHTML}.
     * 
     * @see #setHTML(Vector)
     */
    public default Replaceable setHTML(HTMLNode newHTML)
    {
        // NodeIndex ==> NodeIndex
        if (this.originalSize() == 1)
            return NodeIndex.newNodeIndex(this.originalLocationStart(), newHTML);

        Vector<HTMLNode> v = new Vector<>();
        v.add(newHTML);

        return new ReplaceableAdapter
            (this.originalLocationStart(), this.originalLocationEnd(), v);
    }

    /**
     * Removes all HTML from this {@code Replaceable}, such that's {@link #currentNodes()} would
     * return an empty HTML list.
     * 
     * @return a new replaceable whose original <I><B STYLE='color: red;'>location</B> has not
     * changed</I>, but whose contents are empty.
     * 
     * @see #setHTML(Vector)
     */
    public default Replaceable clearHTML()
    {
        if (currentSize() == 0) return Replaceable.empty(originalLocationStart());

        return new ReplaceableAdapter
            (originalLocationStart(), originalLocationEnd(), new Vector<>());
    }


    // ********************************************************************************************
    // ********************************************************************************************
    // Creating Replacebles, using the Adapter, avoiding the Concrete-Class' exception checks.
    // ********************************************************************************************
    // ********************************************************************************************


    /**
     * Provides a mechanism for creating a {@link SubSection} instance whose {@code html} does not
     * match the size of the {@code location} where that {@code html} is to be placed.
     * 
     * @param location The range in any HTML Page by which the new {@code html} will be replaced.
     * 
     * @param html The html that will ultimately be used to replace the current-html, <I>on a
     * web-page, at the specified {@code location}</I>.
     * 
     * @return An instance of a {@code Replaceable}, that is, in-effect, a {@link SubSection}, but
     * one whose location/bounds do not match the size of the new-{@code html}.
     * 
     * <BR /><BR /><B STYLE='color: red;'>NOTE:</B> This method allows a user to bypass the 
     * exception-check that class {@code SubSection} performs when building an instance of that
     * class.
     */
    public static Replaceable create(DotPair location, Vector<HTMLNode> html)
    { return new ReplaceableAdapter(location.start, location.end + 1, html); }

    /**
     * Creates a new {@code Replaceable} instance whose original-location is just a single-node,
     * but whose new {@code html} may be an arbitrarily-sized html {@code Vector}.
     * 
     * @param location The node in any HTML Page which shall be replaced by {@code 'html'}
     * 
     * @param html The html that will replace the node on an HTML page located at
     * {@code 'location'}
     * 
     * @return An instance of a {@code Replaceable} that is, in effect, a {@link SubSection},
     * but one whose location/bounds are not (necessarily) a single page-index.
     * 
     * <BR /><BR /><B STYLE='color: red;'>NOTE:</B> This method allows a user to bypass the 
     * requirement that a {@code NodeIndex} occupy only a single-node.
     */
    public static Replaceable create(int location, Vector<HTMLNode> html)
    { return new ReplaceableAdapter(location, location + 1, html); }

    /**
     * Creates a new {@code Replaceable} instance whose original-location had zero-length
     * 
     * @param location The location in any HTML Page into which the {@code 'html'} shall be
     * inserted
     * 
     * @param html The html that will be inserted into an HTML Page at index {@code 'location'}
     * 
     * @return An instance of a {@code Replaceable} - whose original-location had a zero-length
     */
    public static Replaceable createInsertion(int location, Vector<HTMLNode> html)
    { return new ReplaceableAdapter(location, location, html); }


    // ********************************************************************************************
    // ********************************************************************************************
    // After updating an HTML-Page, this will incorporate the changed size & location
    // ********************************************************************************************
    // ********************************************************************************************


    /**
     * This method is mostly of internal-use, mainly by
     * {@link ReplaceNodes#r(Vector, Iterable, boolean)}
     * 
     * @param sPos The new location in an html page-{@code Vector} where the contents of this
     * {@code Replaceable} are now located.
     * 
     * @return A new instance, whose html-contents are identical, but is located at {@code 'sPos'}
     * (and having an ending-location of {@code sPos + currentSize()}).
     */
    public default Replaceable moveAndUpdate(int sPos)
    {
        // IMPORTANT: This method is extremely un-important!  It looks kind of unreadable.
        //            All it is doing is REGISTERING the changes to his SubSection or NodeIndex
        //            by building a new SubSection or new NodeIndex.
        //
        // PRIMARILY: Since the *WHOLE POINT* is to make all of the changes to an HTML Page, first,
        //            before doing an update ... Having updated Replaceable's is mostly a waste.
        //            Specifically, after the page has been updated, keeping the sub-parts of the 
        //            page would no longer be necessary!
        //
        // ReplaceNodes: This class offers the option to 'updateReplaceablesAfterBuild' in case
        //            (for whatever reason) the user has decided another round of page updates is
        //            needed.

        final int size = currentSize();

        switch (size)
        {
            case 0: return Replaceable.empty(sPos);
            case 1: return NodeIndex.newNodeIndex(sPos, firstCurrentNode());

            default:
                return new SubSection(
                    // DotPair.end is inclusive, so subtract 1
                    new DotPair(sPos, sPos + size - 1),

                    // The current HTML Vector
                    currentNodes()
                );
        }
    }


    // ********************************************************************************************
    // ********************************************************************************************
    // Creating an Empty Replaceable
    // ********************************************************************************************
    // ********************************************************************************************


    /**
     * Returns an empty {@code Replaceable} (an instance having 0 {@code HTMLNode's}) located at
     * {@code sPos}.
     * 
     * <BR /><BR /><B CLASS=JDDescLabel>NoSuchElementException:</B>
     * 
     * <BR />Attempting to retrieve nodes from the returned-instance will generate a
     * Java {@code NoSuchElementException}.
     * 
     * @param sPos The location of this zero-element {@code Replaceable}
     * @return The new instance.
     */
    public static Replaceable empty(final int sPos)
    { return new ReplaceableAdapter(sPos, sPos, new Vector<>()); }


    // ********************************************************************************************
    // ********************************************************************************************
    // Synthetic
    // ********************************************************************************************
    // ********************************************************************************************


    /**
     * Identifies whether or not {@code 'this'} instance is an anonymous class, that was built from
     * the (internal) {@code ReplaceableAdapter}.
     * 
     * @return {@code TRUE} if {@code 'this'} is <B STYLE='color: red;'>neither</B> an instance
     * that inherits {@code NodeIndex} <B STYLE='color: red;'>nor</B> inherits {@link SubSection}.
     * Such instances are built from an internal {@code ReplaceableAdapter}, and are produced by
     * the methods: {@link #setHTML(Vector)}, {@link #setHTML(HTMLNode)}, {@link #clearHTML()},
     * and {@link #empty(int)}.
     */
    public default boolean isSynthetic() { return false; }
}