package Torello.HTML;

import Torello.HTML.helper.AttrRegEx;

import Torello.Java.StringParse;
import Torello.Java.StrCmpr;
import Torello.Java.StrFilter;

import Torello.HTML.NodeSearch.CSSStrException;
import Torello.HTML.NodeSearch.TextComparitor;

import Torello.JavaDoc.LinkJavaSource;

import static Torello.JavaDoc.Entity.METHOD;
import static Torello.JavaDoc.Entity.FIELD;

import java.util.Vector;
import java.util.Properties;
import java.util.Map;

import java.util.regex.Pattern;
import java.util.regex.Matcher;

import java.util.stream.Stream;

import javax.management.AttributeNotFoundException;

import java.util.function.Predicate;

/**
 * Represents an HTML Element Tag, and is the flagship class of the Java-HTML Library.
 * 
 * <EMBED CLASS='external-html' DATA-FILE-ID=TAG_NODE>
 * <EMBED CLASS='external-html' DATA-FILE-ID=HTML_NODE_SUB_IMG>
 * 
 * @see TextNode
 * @see CommentNode
 * @see HTMLNode
 */
@Torello.JavaDoc.JDHeaderBackgroundImg(EmbedTagFileID="HTML_NODE_SUBCLASS")
public final class TagNode 
    extends HTMLNode 
    implements CharSequence, java.io.Serializable, Cloneable, Comparable<TagNode>
{
    /** <EMBED CLASS='external-html' DATA-FILE-ID=SVUID> */
    public static final long serialVersionUID = 1;


    // ********************************************************************************************
    // ********************************************************************************************
    // NON-STATIC FIELDS
    // ********************************************************************************************
    // ********************************************************************************************


    /** <EMBED CLASS='external-html' DATA-FILE-ID=TAGNODE_TOK> */
    public final String tok;

    /** <EMBED CLASS='external-html' DATA-FILE-ID=TAGNODE_IS_CLOSING> */
    public final boolean isClosing;



    // ********************************************************************************************
    // ********************************************************************************************
    // Package-Private Constructors - NO ERROR CHECKING DONE WHATSOEVER
    // ********************************************************************************************
    // ********************************************************************************************


    // ONLY USED BY THE "TagNodeHelpers" and in conjunction with "Generate Element String"
    // 
    // It presumes that the node was properly constructed and needs to error-checking
    // It is only used for opening TagNode's

    TagNode(String tok, String str)
    {
        super(str);

        this.tok        = HTMLTags.getTag_MEM_HEAP_CHECKOUT_COPY(tok);
        this.isClosing  = false;
    }


    // USED-INTERNALLY - bypasses all checks.  used when creating new HTML Element-Names
    // ONLY: class 'HTMLTags' via method 'addTag(...)' shall ever invoke this constructor.
    //
    // NOTE: This only became necessary because of the MEM_COPY_HEAP optimization.  This
    //       optimization expects that there is already a TagNode with element 'tok' in
    //       the TreeSet, which is always OK - except for the method that CREATES NEW HTML
    //       TAGS... a.k.a. HTMLTags.addTag(String).

    TagNode(String token, TC openOrClosed)
    {
        super("<" + ((openOrClosed == TC.ClosingTags) ? "/" : "") + token + ">");

        // ONLY CHANGE CASE HERE, NOT IN PREVIOUS-LINE.  PAY ATTENTION.  
        this.tok = token.toLowerCase();

        this.isClosing = (openOrClosed == TC.ClosingTags) ? true : false;
    }


    // ********************************************************************************************
    // ********************************************************************************************
    // Public Constructors
    // ********************************************************************************************
    // ********************************************************************************************


    /**
     * <EMBED CLASS='external-html' DATA-FILE-ID=TN_C_DESC_1>
     * 
     * @param s Any valid HTML tag, for instance: {@code <H1>, <A HREF="somoe url">,
     * <DIV ID="some id">} etc...
     * 
     * @throws MalformedTagNodeException If the passed {@code String} wasn't valid - meaning <I>it
     * did not match the regular-expression {@code parser}.</I> 
     * 
     * @throws HTMLTokException If the {@code String} found where the usual HTML token-element is
     * situated <I>is not a valid HTML element</I> then the {@code HTMLTokException} will be
     * thrown.
     * 
     * @see HTMLTags#getTag_MEM_HEAP_CHECKOUT_COPY(String)
     */
    public TagNode(String s)
    {
        super(s);

        // If the second character of the string is a forward-slash, this must be a closing-element
        // For Example: </SPAN>, </DIV>, </A>, etc...

        isClosing = s.charAt(1) == '/';

        // This is the Element & Attribute Matcher used by the RegEx Parser.  If this Matcher
        // doesn't find a match, the parameter 's' cannot be a valid HTML Element.  NOTE: The
        // results of this matcher are also used to retrieve attribute-values, but here below,
        // its results are ignored.

        Matcher m = HTMLRegEx.P1.matcher(s);

        if (! m.find()) throw new MalformedTagNodeException(
            "The parser's regular-expression did not match the constructor-string.\n" +
            "The exact input-string was: [" + s + "]\n" +
            "NOTE:  The parameter-string is included as a field (ex.str) to this Exception.", s
        );

        if ((m.start() != 0) || (m.end() != s.length()))

            throw new MalformedTagNodeException(
                "The parser's regular-expression did not match the entire-string-length of the " +
                "string-parameter to this constructor: m.start()=" + m.start() + ", m.end()=" + 
                m.end() + ".\nHowever, the length of the Input-Parameter String was " +
                '[' + s.length() + "]\nThe exact input-string was: [" + s + "]\nNOTE: The " +
                "parameter-string is included as a field (ex.str) to this Exception.", s
            );

        // MINOR/MAJOR IMPROVEMENT... REUSE THE "ALLOCATED STRING TOKEN" from HTMLTag's class
        // THINK: Let the Garbage Collector take out as many duplicate-strings as is possible..
        // AND SOONER.  DECEMBER 2019: "Optimization" or ... "Improvement"
        // 
        // Get a copy of the 'tok' string that was already allocated on the heap; (OPTIMIZATON)
        //
        // NOTE: There are already myriad strings for the '.str' field.
        // 
        // ALSO: Don't pay much attention to this line if it doesn't make sense... it's not
        //       that important.  If the HTML Token found was not a valid HTML5 token, this field
        //       will be null.
        // 
        // Java 14+ has String.intern() - that's what this is....

        this.tok = HTMLTags.getTag_MEM_HEAP_CHECKOUT_COPY(m.group(1));

        // Now do the usual error check.
        if (this.tok == null) throw new HTMLTokException(
            "The HTML Tag / Token Element that is specified by the input string " +
            "[" + m.group(1).toLowerCase() + "] is not a valid HTML Element Name.\n" +
            "The exact input-string was: [" + s + "]"
        );
    }

    /**
     * Convenience Constructor.
     * <BR />Invokes: {@link #TagNode(String, Properties, Iterable, SD, boolean)}
     * <BR />Passes: null to the Boolean / Key-Only Attributes {@code Iterable}
     */
    public TagNode(
            String      tok,
            Properties  attributes,
            SD          quotes,
            boolean     addEndingForwardSlash
        ) 
    {
        this(
            tok,
            GeneralPurpose.generateElementString(
                tok,
                attributes,
                null, // keyOnlyAttributes,
                quotes,
                addEndingForwardSlash
            ));
    }

    /**
     * <EMBED CLASS='external-html' DATA-FILE-ID=TN_C_DESC_2>
     * @param tok                   <EMBED CLASS='external-html' DATA-FILE-ID=TN_C_TOK>
     * @param attributes            <EMBED CLASS='external-html' DATA-FILE-ID=TN_C_ATTRIBUTES>
     * @param keyOnlyAttributes     <EMBED CLASS='external-html' DATA-FILE-ID=TN_C_KO_ATTRIBUTES>
     * @param quotes                <EMBED CLASS='external-html' DATA-FILE-ID=TN_C_QUOTES>
     * @param addEndingForwardSlash <EMBED CLASS='external-html' DATA-FILE-ID=TN_C_AEFS>
     * @throws InnerTagKeyException <EMBED CLASS='external-html' DATA-FILE-ID=IT_KEY_EX_PROP_TN>
     * @throws QuotesException      <EMBED CLASS='external-html' DATA-FILE-ID=QEX>
     * 
     * @throws HTMLTokException if an invalid HTML 4 or 5 token is not present
     * <B>(check is {@code CASE_INSENSITIVE})</B>, or a token which has been registered with class
     * {@code HTMLTags}.
     * 
     * @see InnerTagKeyException#check(String, String)
     * @see QuotesException#check(String, SD, String)
     */
    public TagNode(
            String              tok,
            Properties          attributes,
            Iterable<String>    keyOnlyAttributes,
            SD                  quotes,
            boolean             addEndingForwardSlash
        )
    {
        this(
            tok,
            GeneralPurpose.generateElementString
                (tok, attributes, keyOnlyAttributes, quotes, addEndingForwardSlash)
        );
    }


    // ********************************************************************************************
    // ********************************************************************************************
    // HTMLNode Overidden - Loop & Stream Optimization Methods
    // ********************************************************************************************
    // ********************************************************************************************


    /**
     * This method identifies that {@code 'this'} instance of (abstract parent-class)
     * {@link HTMLNode} is, indeed, an instance of sub-class {@code TagNode}.
     *
     * <BR /><BR /><B CLASS=JDDescLabel>Final Method:</B>
     * 
     * <BR />This method is final, and cannot be modified by sub-classes.
     * 
     * @return This method shall always return {@code TRUE}  It overrides the parent-class
     * {@code HTMLNode} method {@link #isTagNode()}, which always returns {@code FALSE}.
     */
    @Override
    public final boolean isTagNode() { return true; }

    /**
     * <EMBED CLASS='external-html' DATA-FILE-ID=TN_IF_TN_DESC>
     * <BR /><BR /><B CLASS=JDDescLabel>Final Method:</B>
     * <BR />This method is final, and cannot be modified by sub-classes.
     * @return <EMBED CLASS='external-html' DATA-FILE-ID=TN_IF_TN_RET>
     */
    @Override
    public final TagNode ifTagNode() { return this; }

    /**
     * <EMBED CLASS='external-html' DATA-FILE-ID=TN_OPENTAG_PWA_DESC>
     * <BR /><BR /><B CLASS=JDDescLabel>Final Method:</B>
     * <BR />This method is final, and cannot be modified by sub-classes.
     * @return <EMBED CLASS='external-html' DATA-FILE-ID=TN_OPENTAG_PWA_RET>
     */
    @Override
    public final TagNode openTagPWA()
    {
        // Closing TagNode's simply may not have attributes
        if (this.isClosing) return null;

        // A TagNode whose '.str' field is not AT LEAST 4 characters LONGER than the length of the
        // HTML-Tag / Token, simply cannot have an attribute.
        //
        // NOTE: Below is the shortest possible HTML tag that could have an attribute.
        // COMPUTE: '<' + TOK.LENGTH + SPACE + 'c' + '>'

        if (this.str.length() < (this.tok.length() + 4)) return null;

        // This TagNode is an opening HTML tag (like <DIV ...>, rather than </DIV>),
        // and there are at least two additional characters after the token, such as: <DIV A...>
        // It is not guaranteed that this tag has attributes, but it is possibly - based on these
        /// optimization methods, and further investigation would have merit.

        return this;
    }

    /**
     * This is a loop-optimization method that makes finding opening {@code TagNode's} - <B>with
     * attribute-</B><B STYLE='color: red;'>values</B> - quites a bit faster.  All {@link HTMLNode}
     * subclasses implement this method, but only {@code TagNode} instances will ever return a
     * non-null value.
     * 
     * <BR /><BR /><B CLASS=JDDescLabel>Final Method:</B>
     * 
     * <BR />This method is final, and cannot be modified by sub-classes.
     * 
     * @return Returns null if and only if {@code 'this'} instance' {@link #isClosing} field is
     * false.  When a non-null return-value is acheived, that value will always be {@code 'this'}
     * instance.
     */
    @Override
    public final TagNode openTag()
    { return isClosing ? null : this; }

    /**
     * This method is an optimization method that overrides the one by the same name in class
     * {@link HTMLNode}.
     * 
     * {@inheritdoc}
     */
    @Override
    public boolean isOpenTagPWA()
    {
        if (this.isClosing) return false;
        if (this.str.length() < (this.tok.length() + 4)) return false;
        return true;
    }

    /**
     * This method is an optimization method that overrides the one by the same name in class
     * {@link HTMLNode}.
     * 
     * {@inheritdoc}
     */
    @Override
    public boolean isOpenTag()
    { return ! isClosing; }


    // ********************************************************************************************
    // ********************************************************************************************
    // isTag
    // ********************************************************************************************
    // ********************************************************************************************


    /**
     * <EMBED CLASS='external-html' DATA-FILE-ID=TN_IS_TAG1_DESC>
     * @param possibleTags  A non-null list of potential HTML tags to be checked again {@link #tok}
     * @return              <EMBED CLASS='external-html' DATA-FILE-ID=TN_IS_TAG1_RET>
     * @see                 #tok
     */
    public boolean isTag(String... possibleTags)
    { 
        for (String htmlTag : possibleTags) if (htmlTag.equalsIgnoreCase(this.tok)) return true;
        return false;
    }

    /**
     * <EMBED CLASS='external-html' DATA-FILE-ID=TN_IS_TAG_EX1_DESC>
     * @param possibleTags  A non-null list of potential HTML tags to be checked again {@link #tok}
     * @return              <EMBED CLASS='external-html' DATA-FILE-ID=TN_IS_TAG_EX1_RET>
     * @see                 #tok
     * @see                 #isTag(String[])
     */
    public boolean isTagExcept(String... possibleTags)
    { 
        for (String htmlTag : possibleTags) if (htmlTag.equalsIgnoreCase(this.tok)) return false;
        return true;
    }

    /**
     * <EMBED CLASS='external-html' DATA-FILE-ID=TN_IS_TAG2_DESC>
     * @param tagCriteria   <EMBED CLASS='external-html' DATA-FILE-ID=TN_IS_TAG2_PARAM>
     * @param possibleTags  A non-null list of potential HTML tags to be checked again {@link #tok}
     * @return              <EMBED CLASS='external-html' DATA-FILE-ID=TN_IS_TAG2_RET>
     * @see                 #tok
     */
    @LinkJavaSource(handle="IsTag", name="isTag")
    public boolean isTag(TC tagCriteria, String... possibleTags)
    { return IsTag.isTag(this, tagCriteria, possibleTags); }

    /**
     * <EMBED CLASS='external-html' DATA-FILE-ID=TN_IS_TAG_EX2_DESC>
     * @param tagCriteria   <EMBED CLASS='external-html' DATA-FILE-ID=TN_IS_TAG_EX2_PARAM>
     * @param possibleTags  A non-null list of potential HTML tags to be checked again {@link #tok}
     * @return              <EMBED CLASS='external-html' DATA-FILE-ID=TN_IS_TAG_EX2_RET>
     * @see                 #tok
     */
    @LinkJavaSource(handle="IsTag", name="isTagExcept")
    public boolean isTagExcept(TC tagCriteria, String... possibleTags)
    { return IsTag.isTagExcept(this, tagCriteria, possibleTags); }


    // ********************************************************************************************
    // ********************************************************************************************
    // Main Method 'AV'
    // ********************************************************************************************
    // ********************************************************************************************


    /**
     * <EMBED CLASS='external-html' DATA-FILE-ID=TN_AV_DESC>
     * <EMBED CLASS='external-html' DATA-FILE-ID=TN_AV_DESC_EXAMPLE>
     * @param innerTagAttribute <EMBED CLASS='external-html' DATA-FILE-ID=TN_AV_ITA>
     * @return                  <EMBED CLASS='external-html' DATA-FILE-ID=TN_AV_RET>
     * @see StringParse#ifQuotesStripQuotes(String)
     */
    @LinkJavaSource(handle="GetSetAttr", name="AV")
    public String AV(String innerTagAttribute)
    { return GetSetAttr.AV(this, innerTagAttribute, false); }

    /**
     * Identical to {@link #AV(String)}, except that if the
     * Attribute-<B STYLE='color: red;'>value</B> had quotes surrounding it, those are included in
     * the returned {@code String}.
     */
    // To-Do, finish this after brekfast
    // public String preserveQuotesAV(String innerTagAttribute)
    // { return GetSetAttr.AV(this, innerTagAttribute, true); }

    /**
     * <B STYLE='color: red;'>AVOPT: Attribute-Value - Optimized</B>
     * 
     * <BR /><BR /> This is an "optimized" version of method {@link #AV(String)}.  This method does
     * the exact same thing as {@code AV(...)}, but leaves out parameter-checking and
     * error-checking. This is used internally (and repeatedly) by the NodeSearch Package Search
     * Loops.
     * 
     * @param innerTagAttribute This is the inner-tag / attribute <B STYLE='color: red;'>name</B>
     * whose <B STYLE='color: red;'>value</B> is hereby being requested.
     * 
     * @return {@code String}-<B STYLE='color: red;'>value</B> of this inner-tag / attribute.
     * 
     * @see StringParse#ifQuotesStripQuotes(String)
     * @see #str
     */
    @LinkJavaSource(handle="AttrRegEx", entity=FIELD, name="KEY_VALUE_REGEX")
    public String AVOPT(String innerTagAttribute)
    {
        // COPIED DIRECTLY FROM class TagNode, leaves off initial tests.

        // Matches "Attribute / Inner-Tag Key-Value" Pairs.
        Matcher m = AttrRegEx.KEY_VALUE_REGEX.matcher(this.str);

        // This loop iterates the KEY_VALUE PAIRS THAT HAVE BEEN FOUND.
        /// NOTE: The REGEX Matches on Key-Value Pairs.

        while (m.find())

            // m.group(2) is the "KEY" of the Attribute KEY-VALUE Pair
            // m.group(3) is the "VALUE" of the Attribute.

            if (m.group(2).equalsIgnoreCase(innerTagAttribute))
                return StringParse.ifQuotesStripQuotes(m.group(3));

        // This means the attribute name provided to parameter 'innerTagAttribute' was not found.
        return null;
    }


    // ********************************************************************************************
    // ********************************************************************************************
    // Attribute Modify-Value methods
    // ********************************************************************************************
    // ********************************************************************************************


    /**
     * <EMBED CLASS='external-html' DATA-FILE-ID=TN_SET_AV_DESC>
     * @param attribute <EMBED CLASS='external-html' DATA-FILE-ID=TN_SET_AV_ATTR>
     * 
     * @param value Any valid attribute-<B STYLE='color: red;'>value</B>.  This parameter may not
     * be null, or a {@code NullPointerException} will throw.
     * 
     * @param quote                     <EMBED CLASS='external-html' DATA-FILE-ID=TN_SET_AV_QUOTE>
     * @throws InnerTagKeyException     <EMBED CLASS='external-html' DATA-FILE-ID=IT_KEY_EX_TN>
     * @throws QuotesException          <EMBED CLASS='external-html' DATA-FILE-ID=QEX>
     * @throws ClosingTagNodeException  <EMBED CLASS='external-html' DATA-FILE-ID=CTNEX>
     * 
     * @throws HTMLTokException If an invalid HTML 4 or 5 token is not present 
     * (<B>{@code CASE_INSENSITIVE}</B>).
     * 
     * @return <EMBED CLASS='external-html' DATA-FILE-ID=TN_SET_AV_RET>
     * @see ClosingTagNodeException#check(TagNode)
     * @see #setAV(Properties, SD)
     * @see #str
     * @see #isClosing
     */
    @LinkJavaSource(handle="GetSetAttr", name="setAV", paramCount=4)
    public TagNode setAV(String attribute, String value, SD quote)
    { return GetSetAttr.setAV(this, attribute, value, quote); }

    /**
     * <EMBED CLASS='external-html' DATA-FILE-ID=TN_SET_AV2_DESC>
     * @param attributes These are the new attribute <B STYLE='color: red;'>key-value</B> pairs to
     * be inserted.
     * 
     * @param defaultQuote <EMBED CLASS='external-html' DATA-FILE-ID=TN_SET_AV2_DQ_PARAM>
     * @throws InnerTagKeyException <EMBED CLASS='external-html' DATA-FILE-ID=IT_KEY_EX_PROP_TN>
     * 
     * @throws QuotesException if there are "quotes within quotes" problems, due to the
     * <B STYLE='color: red;'>values</B> of the <B STYLE='color: red;'>key-value</B> pairs.
     * 
     * @throws HTMLTokException if an invalid HTML 4 or 5 token is not present 
     * <B>({@code CASE_INSENSITIVE})</B>
     * 
     * @throws ClosingTagNodeException <EMBED CLASS='external-html' DATA-FILE-ID=CTNEX>
     *
     * @return <EMBED CLASS='external-html' DATA-FILE-ID=TN_SET_AV2_RET>
     * @see ClosingTagNodeException#check(TagNode)
     * @see #setAV(String, String, SD)
     * @see #isClosing
     */
    @LinkJavaSource(handle="GetSetAttr", name="setAV", paramCount=3)
    public TagNode setAV(Properties attributes, SD defaultQuote)
    { return GetSetAttr.setAV(this, attributes, defaultQuote); }

    /**
     * <EMBED CLASS='external-html' DATA-FILE-ID=TN_APD_AV_DESC>
     * @param attribute                 <EMBED CLASS=external-html DATA-FILE-ID=TN_APD_AV_P_ATTR>
     * @param appendStr                 <EMBED CLASS=external-html DATA-FILE-ID=TN_APD_AV_P_APDSTR>
     * @param startOrEnd                <EMBED CLASS=external-html DATA-FILE-ID=TN_APD_AV_P_S_OR_E>
     * @param quote                     <EMBED CLASS=external-html DATA-FILE-ID=TGND_QUOTE_EXPL>
     *                                  <EMBED CLASS=external-html DATA-FILE-ID=TN_APD_AV_P_QXTRA>
     * @return                          <EMBED CLASS=external-html DATA-FILE-ID=TN_APD_AV_RET>
     * @see                             #AV(String)
     * @see                             #setAV(String, String, SD)
     * @see                             ClosingTagNodeException#check(TagNode)
     * @throws ClosingTagNodeException  <EMBED CLASS='external-html' DATA-FILE-ID=CTNEX>
     * 
     * @throws QuotesException The <B><A HREF=#QUOTEEX>rules</A></B> for quotation usage apply
     * here too, and see that explanation for how how this exception could be thrown.
     */
    @LinkJavaSource(handle="GetSetAttr", name="appendToAV")
    public TagNode appendToAV(String attribute, String appendStr, boolean startOrEnd, SD quote)
    { return GetSetAttr.appendToAV(this, attribute, appendStr, startOrEnd, quote); }   


    // ********************************************************************************************
    // ********************************************************************************************
    // Attribute Removal Operations
    // ********************************************************************************************
    // ********************************************************************************************


    /**
     * Convenience Method.
     * <BR />See Documentation: {@link #removeAttributes(String[])}
     */
    @LinkJavaSource(handle="RemoveAttributes", name="removeAttributes")
    public TagNode remove(String attributeName)
    {
        return RemoveAttributes.removeAttributes
            (this, (String attr) -> ! attr.equalsIgnoreCase(attributeName));
    }

    /**
     * <EMBED CLASS='external-html' DATA-FILE-ID=TN_REM_ATTR_DESC>
     * @param attributes                <EMBED CLASS='external-html' DATA-FILE-ID=TN_REM_ATTR_ATTR>
     * @return                          <EMBED CLASS='external-html' DATA-FILE-ID=TN_REM_ATTR_RET>
     * @throws ClosingTagNodeException  <EMBED CLASS='external-html' DATA-FILE-ID=CTNEX>
     * @see                             ClosingTagNodeException#check(TagNode)
     */
    @LinkJavaSource(handle="RemoveAttributes", name="removeAttributes")
    public TagNode removeAttributes(String... attributes)
    {
        return RemoveAttributes.removeAttributes
            (this, (String attr) -> StrCmpr.equalsNAND_CI(attr, attributes));
    }

    /**
     * Filter's attributes using an Attribute-<B STYLE='color:red'>Name</B>
     * {@code String-Predicate}
     * 
     * @param attrNameTest Any Java {@code String-Predicate}.  It will be used to test whether or
     * not to keep or filter/reject an attribute from {@code 'this' TagNode}.
     * 
     * <BR /><BR /><B STYLE='color: red;'>NOTE:</B> Like all filter-{@code Predicate's}, this
     * test's expected behavior is such that it should return {@code TRUE} when it would like to 
     * keep an attribute having a particular <B STYLE='color: red;'>name</B>, and return
     * {@code FALSE} when it would like to see the attribute removed from the HTML Tag.
     * 
     * @return Removes any Attributes whoe <B STYLE='color: red;'>name</B> as per the rules of the
     * User-Provided {@code String-Predicate} parameter {@code 'attrNameTest'}.  As with all 
     * {@code TagNode} modification operations, if any changes are, indeed, made to a new instance 
     * of {@code TagNode} will be created and returned.
     */
    @LinkJavaSource(handle="RemoveAttributes", name="removeAttributes")
    public TagNode removeAttributes(Predicate<String> attrNameTest)
    { return RemoveAttributes.removeAttributes(this, attrNameTest); }

    /**
     * <EMBED CLASS='external-html' DATA-FILE-ID=TN_REM_ALL_AV_DESC>
     * @return                          <EMBED CLASS=external-html DATA-FILE-ID=TN_REM_ALL_AV_RET>
     * @throws ClosingTagNodeException  <EMBED CLASS=external-html DATA-FILE-ID=CTNEX>
     * @see                             ClosingTagNodeException#check(TagNode)
     * @see                             #getInstance(String, TC)
     * @see                             TC#OpeningTags
     */
    public TagNode removeAllAV()
    {
        ClosingTagNodeException.check(this);

        // NOTE: We *CANNOT* use the 'tok' field to instantiate the TagNode here, because the 'tok'
        // String-field is *ALWAYS* guaranteed to be in a lower-case format.  The 'str'
        // String-field, however uses the original case that was found on the HTML Document by the
        // parser (or in the Constructor-Parameters that were passed to construct 'this' instance
        // of TagNode.

        return getInstance(this.str.substring(1, 1 + tok.length()), TC.OpeningTags);
    }


    // ********************************************************************************************
    // ********************************************************************************************
    // Retrieve all attributes
    // ********************************************************************************************
    // ********************************************************************************************


    /**
     * Convenience Method.
     * <BR />See Documentation: {@link #allAV(boolean, boolean)}
     * <BR />Attribute-<B STYLE='color: red;'>names</B> will be in lower-case.
     */
    @LinkJavaSource(handle="RetrieveAllAttr", name="allAV")
    public Properties allAV()
    { return RetrieveAllAttr.allAV(this, false, false);  }

    /**
     * <EMBED CLASS='external-html' DATA-FILE-ID=TN_ALL_AV_DESC>
     * @param keepQuotes        <EMBED CLASS='external-html' DATA-FILE-ID=TN_ALL_AV_KQ_PARAM>
     * @param preserveKeysCase  <EMBED CLASS='external-html' DATA-FILE-ID=TN_ALL_AV_PKC_PARAM>
     *                          <EMBED CLASS='external-html' DATA-FILE-ID=TAGNODE_PRESERVE_C>
     * @return                  <EMBED CLASS='external-html' DATA-FILE-ID=TN_ALL_AV_RET>
     * @see                     StringParse#ifQuotesStripQuotes(String)
     */
    @LinkJavaSource(handle="RetrieveAllAttr", name="allAV")
    public Properties allAV(boolean keepQuotes, boolean preserveKeysCase)
    { return RetrieveAllAttr.allAV(this, keepQuotes, preserveKeysCase); }

    /**
     * Convenience Method.
     * <BR />See Documentation: {@link #allAN(boolean, boolean)}
     * <BR />Attribute-<B STYLE='color: red;'>names</B> will be in lower-case
     */
    @LinkJavaSource(handle="RetrieveAllAttr", name="allAN")
    public Stream<String> allAN()
    { return RetrieveAllAttr.allAN(this, false, false); }

    /**
     * This method will only return a list of attribute-<B STYLE='color: red;'>names</B>.  The
     * attribute-<B STYLE="color: red">values</B> shall <B>NOT</B> be included in the result.  The
     * {@code String's} returned can have their "case-preserved" by passing {@code TRUE} to the
     * input boolean parameter {@code 'preserveKeysCase'}.
     *
     * @param preserveKeysCase If this is parameter receives {@code TRUE} then the case of the
     * attribute-<B STYLE='color: red;'>names</B> shall be preserved.
     *
     * <EMBED CLASS='external-html' DATA-FILE-ID=TAGNODE_PRESERVE_C>
     *
     * @param includeKeyOnlyAttributes When this parameter receives {@code TRUE}, then any
     * "Boolean Attributes" or "Key-Only, No-Value-Assignment" Inner-Tags will <B>ALSO</B> be
     * included in the {@code Stream<String>} returned by this method.
     *
     * @return an instance of {@code Stream<String>} containing all
     * attribute-<B STYLE='color: red;'>names</B> identified in {@code 'this'} instance of
     * {@code TagNode}.  A {@code java.util.stream.Stream} is used because it's contents can easily
     * be converted to just about any data-type.  
     *
     * <EMBED CLASS='external-html' DATA-FILE-ID=STRMCNVT>
     *
     * <BR /><B>NOTE:</B> This method shall never return {@code 'null'} - even if there are no 
     * attribute <B STYLE='color: red;'>key-value</B> pairs contained by {@code 'this' TagNode}.
     * If there are strictly zero attributes, an empty {@code Stream} shall be returned, instead.
     * 
     * @see #allKeyOnlyAttributes(boolean)
     * @see #allAN()
     */
    @LinkJavaSource(handle="RetrieveAllAttr", name="allAN")
    public Stream<String> allAN(boolean preserveKeysCase, boolean includeKeyOnlyAttributes)
    { return RetrieveAllAttr.allAN(this, preserveKeysCase, includeKeyOnlyAttributes); }


    // ********************************************************************************************
    // ********************************************************************************************
    // Key only attributes
    // ********************************************************************************************
    // ********************************************************************************************


    /**
     * <EMBED CLASS='external-html' DATA-FILE-ID=TN_ALL_KOA_DESC>
     * @param preserveKeysCase  <EMBED CLASS='external-html' DATA-FILE-ID=TN_ALL_KOA_PKC>
     *                          <EMBED CLASS='external-html' DATA-FILE-ID=TAGNODE_PRESERVE_C>
     * @return                  <EMBED CLASS='external-html' DATA-FILE-ID=TN_ALL_KOA_RET>
     *                          <EMBED CLASS='external-html' DATA-FILE-ID=STRMCNVT>
     */
    @LinkJavaSource(handle="KeyOnlyAttributes", name="allKeyOnlyAttributes")
    public Stream<String> allKeyOnlyAttributes(boolean preserveKeysCase)
    { return KeyOnlyAttributes.allKeyOnlyAttributes(this, preserveKeysCase); }

    /**
     * <EMBED CLASS='external-html' DATA-FILE-ID=TN_HAS_KOA_DESC>
     * @param keyOnlyAttribute          <EMBED CLASS='external-html' DATA-FILE-ID=TN_HAS_KOA_KOA>
     * @return                          <EMBED CLASS='external-html' DATA-FILE-ID=TN_HAS_KOA_RET>
     * @throws IllegalArgumentException <EMBED CLASS='external-html' DATA-FILE-ID=TN_HAS_KOA_IAEX>
     */
    @LinkJavaSource(handle="KeyOnlyAttributes", name="hasKeyOnlyAttribute")
    public boolean hasKeyOnlyAttribute(String keyOnlyAttribute)
    { return KeyOnlyAttributes.hasKeyOnlyAttribute(this, keyOnlyAttribute); }


    // ********************************************************************************************
    // ********************************************************************************************
    // testAV
    // ********************************************************************************************
    // ********************************************************************************************


    /**
     * Convenience Method.
     * <BR />See Documentation: {@link #testAV(String, Predicate)}
     * <BR />Passes: {@code String.equalsIgnoreCase(attributeValue)} to the Test-{@code Predicate}
     */
    @LinkJavaSource(handle="HasAndTest", name="testAV")
    @LinkJavaSource(handle="AttrRegEx", entity=FIELD, name="KEY_VALUE_REGEX")
    public boolean testAV(String attributeName, String attributeValue)
    {
        return HasAndTest.testAV
            (this, attributeName, (String s) -> s.equalsIgnoreCase(attributeValue));
    }

    /**
     * Convenience Method.
     * <BR />See Documentation: {@link #testAV(String, Predicate)}
     * <BR />Passes: {@code attributeValueTest.asPredicate()} to the Test-{@code Predicate}
     */
    @LinkJavaSource(handle="HasAndTest", name="testAV")
    @LinkJavaSource(handle="AttrRegEx", entity=FIELD, name="KEY_VALUE_REGEX")
    public boolean testAV(String attributeName, Pattern attributeValueTest)
    { return HasAndTest.testAV(this, attributeName, attributeValueTest.asPredicate()); }

    /**
     * Convenience Method.
     * <BR />See Documentation: {@link #testAV(String, Predicate)}
     * <BR />Passes: {@link TextComparitor#test(String, String[])} to the Test-{@code Predicate}
     */
    @LinkJavaSource(handle="HasAndTest", name="testAV")
    @LinkJavaSource(handle="AttrRegEx", entity=FIELD, name="KEY_VALUE_REGEX")
    public boolean testAV
        (String attributeName, TextComparitor attributeValueTester, String... compareStrs)
    {
        return HasAndTest.testAV
            (this, attributeName, (String s) -> attributeValueTester.test(s, compareStrs));
    }

    /**
     * <EMBED CLASS='external-html' DATA-FILE-ID=TN_TEST_AV_DESC>
     * @param attributeName         <EMBED CLASS='external-html' DATA-FILE-ID=TN_TEST_AV_PARAM>
     * @param attributeValueTest    Any {@code java.util.function.Predicate<String>}
     * @return                      <EMBED CLASS='external-html' DATA-FILE-ID=TN_TEST_AV_RET>
     * @see                         StringParse#ifQuotesStripQuotes(String)
     */
    @LinkJavaSource(handle="HasAndTest", name="testAV")
    @LinkJavaSource(handle="AttrRegEx", entity=FIELD, name="KEY_VALUE_REGEX")
    public boolean testAV(String attributeName, Predicate<String> attributeValueTest)
    { return HasAndTest.testAV(this, attributeName, attributeValueTest); }


    // ********************************************************************************************
    // ********************************************************************************************
    // has-attribute boolean-logic methods
    // ********************************************************************************************
    // ********************************************************************************************


    /**
     * Convenience Method.
     * <BR />See Documentation: {@link #hasXOR(boolean, String...)}
     * <BR />Passes: AND Boolean Logic
     * <BR />Checks that <B STYLE='color: red;'><I>all</I></B> Attributes are found
     */
    @LinkJavaSource(handle="HasAndTest", name="hasLogicOp")
    @LinkJavaSource(handle="AttrRegEx", entity=FIELD, name="KEY_VALUE_REGEX")
    public boolean hasAND(boolean checkAttributeStringsForErrors, String... attributes)
    {
        // First-Function:  Tells the logic to *IGNORE* intermediate matches (returns NULL)
        //                  (This is *AND*, so wait until all attributes have been found, or at
        //                  the very least all tags in the element tested, and failed.
        //
        // Second-Function: At the End of the Loops, all Attributes have either been found, or
        //                  at least all attributes in 'this' tag have been tested.  Note that the
        //                  first-function is only called on a MATCH, and that 'AND' requires to
        //                  defer a response until all attributes have been tested..  Here, simply
        //                  RETURN WHETHER OR NOT the MATCH-COUNT equals the number of matches in
        //                  the user-provided String-array.

        return HasAndTest.hasLogicOp(
            this,
            checkAttributeStringsForErrors,
            (int matchCount) -> null,
            (int matchCount) -> (matchCount == attributes.length),
            attributes
        );
    }

    /**
     * Convenience Method.
     * <BR />See Documentation: {@link #hasXOR(boolean, String...)}
     * <BR />Passes: OR Boolean Logic
     * <BR />Checks that <B STYLE='color: red;'><I>at least one</I></B> of the Attributes match
     */
    @LinkJavaSource(handle="HasAndTest", name="hasLogicOp")
    @LinkJavaSource(handle="AttrRegEx", entity=FIELD, name="KEY_VALUE_REGEX")
    public boolean hasOR(boolean checkAttributeStringsForErrors, String... attributes)
    {
        // First-Function:  Tells the logic to return TRUE on any match IMMEDIATELY
        //
        // Second-Function: At the End of the Loops, all Attributes have been tested.  SINCE the
        //                  previous function returns on match immediately, AND SINCE this is an
        //                  OR, therefore FALSE must be returned (since there were no matches!)

        return HasAndTest.hasLogicOp(
            this,
            checkAttributeStringsForErrors,
            (int matchCount) -> true,
            (int matchCount) -> false,
            attributes
        );
    }

    /**
     * Convenience Method.
     * <BR />See Documentation: {@link #hasXOR(boolean, String...)}
     * <BR />Passes: NAND Boolean Logic
     * <R />Checks that <B STYLE='color: red;'><I>none</I></B> of the Attributes match
     */
    @LinkJavaSource(handle="HasAndTest", name="hasLogicOp")
    @LinkJavaSource(handle="AttrRegEx", entity=FIELD, name="KEY_VALUE_REGEX")
    public boolean hasNAND(boolean checkAttributeStringsForErrors, String... attributes)
    {
        // First-Function: Tells the logic to return FALSE on any match IMMEDIATELY
        //
        // Second-Function: At the End of the Loops, all Attributes have been tested.  SINCE
        //                  the previous function returns on match immediately, AND SINCE this is
        //                  a NAND, therefore TRUE must be returned (since there were no matches!)

        return HasAndTest.hasLogicOp(
            this,
            checkAttributeStringsForErrors,
            (int matchCount) -> false,
            (int matchCount) -> true,
            attributes
        );
    }

    /**
     * <BR />Passes: XOR Boolean Logic
     * <BR />Checks that <B STYLE='color: red;'><I>precisely-one</I></B> Attribute is found
     * <BR /><BR /><IMG SRC='doc-files/img/hasAND.png' CLASS=JDIMG ALT=Example>
     * 
     * @param checkAttributeStringsForErrors
     * <EMBED CLASS='external-html' DATA-FILE-ID=TAGNODE_HAS_BOOL>
     * 
     * <BR /><BR /><B>NOTE:</B> If this method is passed a zero-length {@code String}-array to the
     * {@code 'attributes'} parameter, this method shall exit immediately and return {@code FALSE}.
     * 
     * @throws InnerTagKeyException If any of the {@code 'attributes'} are not valid HTML
     * attributes, <I><B>and</B></I> the user has passed {@code TRUE} to parameter
     * {@code checkAttributeStringsForErrors}.
     * 
     * @throws NullPointerException     If any of the {@code 'attributes'} are null.
     * @throws ClosingTagNodeException  <EMBED CLASS='external-html' DATA-FILE-ID=CTNEX>
     * @throws IllegalArgumentException If the {@code 'attributes'} parameter has length zero.
     * @see                             InnerTagKeyException#check(String[])
     */
    @LinkJavaSource(handle="HasAndTest", name="hasLogicOp")
    @LinkJavaSource(handle="AttrRegEx", entity=FIELD, name="KEY_VALUE_REGEX")
    public boolean hasXOR(boolean checkAttributeStringsForErrors, String... attributes)
    {
        // First-Function: Tells the logic to IGNORE the FIRST MATCH, and any matches afterwards
        //                 should produce a FALSE result immediately
        //                 (XOR means ==> one-and-only-one)
        //
        // Second-Function: At the End of the Loops, all Attributes have been tested.  Just
        //                  return whether or not the match-count is PRECISELY ONE.

        return HasAndTest.hasLogicOp(
            this,
            checkAttributeStringsForErrors,
            (int matchCount) -> (matchCount == 1) ? null : false,
            (int matchCount) -> (matchCount == 1),
            attributes
        );
    }


    // ********************************************************************************************
    // ********************************************************************************************
    // has methods - extended, variable attribute-names
    // ********************************************************************************************
    // ********************************************************************************************


    /**
     * Convenience Method.
     * <BR />See Documentation: {@link #has(Predicate)}
     * <BR />Passes: {@code String.equalsIgnoreCase(attributeName)} as the test-{@code Predicate}
     */
    @LinkJavaSource(handle="HasAndTest", name="has")
    @LinkJavaSource(handle="AttrRegEx", entity=FIELD, name="KEY_VALUE_REGEX")
    public boolean has(String attributeName)
    { return HasAndTest.has(this, (String s) -> s.equalsIgnoreCase(attributeName)); }

    /**
     * Convenience Method.
     * <BR />See Documentation: {@link #has(Predicate)}
     * <BR />Passes: {@code Pattern.asPredicate()}
     */
    @LinkJavaSource(handle="HasAndTest", name="has")
    @LinkJavaSource(handle="AttrRegEx", entity=FIELD, name="KEY_VALUE_REGEX")
    public boolean has(Pattern attributeNameRegExTest)
    { return HasAndTest.has(this, attributeNameRegExTest.asPredicate()); }

    /**
     * Convenience Method.
     * <BR />See Documentation: {@link #has(Predicate)}
     * <BR />Passes: {@link TextComparitor#test(String, String[])} as the test-{@code Predicate}
     */
    @LinkJavaSource(handle="HasAndTest", name="has")
    @LinkJavaSource(handle="AttrRegEx", entity=FIELD, name="KEY_VALUE_REGEX")
    public boolean has(TextComparitor tc, String... compareStrs)
    { return HasAndTest.has(this, (String s) -> tc.test(s, compareStrs)); }

    /**
     * <EMBED CLASS='external-html' DATA-FILE-ID=TN_HAS_DESC2>
     * <EMBED CLASS='external-html' DATA-FILE-ID=TAGNODE_HAS_NOTE>
     * @param attributeNameTest <EMBED CLASS='external-html' DATA-FILE-ID=TN_HAS_ANT>
     * @return                  <EMBED CLASS='external-html' DATA-FILE-ID=TN_HAS_RET2>
     * @see                     StrFilter
     */
    @LinkJavaSource(handle="HasAndTest", name="has")
    @LinkJavaSource(handle="AttrRegEx", entity=FIELD, name="KEY_VALUE_REGEX")
    public boolean has(Predicate<String> attributeNameTest)
    { return HasAndTest.has(this, attributeNameTest); }


    // ********************************************************************************************
    // ********************************************************************************************
    // hasValue(...) methods
    // ********************************************************************************************
    // ********************************************************************************************


    /**
     * Convenience Method.
     * <BR />See Documentation: {@link #hasValue(Predicate, boolean, boolean)}
     * <BR />Passes: {@code String.equals(attributeValue)} as the test-{@code Predicate}
     */
    @LinkJavaSource(handle="HasAndTest", name="hasValue")
    @LinkJavaSource(handle="AttrRegEx", entity=FIELD, name="KEY_VALUE_REGEX")
    public Map.Entry<String, String> hasValue
        (String attributeValue, boolean retainQuotes, boolean preserveKeysCase)
    {
        return HasAndTest.hasValue
            (this, (String s) -> attributeValue.equals(s), retainQuotes, preserveKeysCase);
    }

    /**
     * Convenience Method.
     * <BR />See Documentation: {@link #hasValue(Predicate, boolean, boolean)}
     * <BR />Passes: {@code attributeValueRegExTest.asPredicate()}
     */
    @LinkJavaSource(handle="HasAndTest", name="hasValue")
    @LinkJavaSource(handle="AttrRegEx", entity=FIELD, name="KEY_VALUE_REGEX")
    public Map.Entry<String, String> hasValue
        (Pattern attributeValueRegExTest, boolean retainQuotes, boolean preserveKeysCase)
    {
        return HasAndTest.hasValue
            (this, attributeValueRegExTest.asPredicate(), retainQuotes, preserveKeysCase);
    }

    /**
     * Convenience Method.
     * <BR />See Documentation: {@link #hasValue(Predicate, boolean, boolean)}
     * <BR />Passes: {@link TextComparitor#test(String, String[])} as the test-{@code Predicate}
     */
    @LinkJavaSource(handle="HasAndTest", name="hasValue")
    @LinkJavaSource(handle="AttrRegEx", entity=FIELD, name="KEY_VALUE_REGEX")
    public Map.Entry<String, String> hasValue(
            boolean retainQuotes, boolean preserveKeysCase, TextComparitor attributeValueTester,
            String... compareStrs
        )
    {
        return HasAndTest.hasValue(
            this,
            (String s) -> attributeValueTester.test(s, compareStrs),
            retainQuotes,
            preserveKeysCase
        );
    }

    /**
     * <EMBED CLASS='external-html' DATA-FILE-ID=TN_HASVAL_DESC2>
     * <EMBED CLASS='external-html' DATA-FILE-ID=TN_HASVAL_DNOTE>
     * @param attributeValueTest    <EMBED CLASS='external-html' DATA-FILE-ID=TN_HASVAL_AVT>
     * @param retainQuotes          <EMBED CLASS='external-html' DATA-FILE-ID=TN_HASVAL_RQ>
     * @param preserveKeysCase      <EMBED CLASS='external-html' DATA-FILE-ID=TN_HASVAL_PKC>
     *                              <EMBED CLASS='external-html' DATA-FILE-ID=TAGNODE_PRESERVE_C>
     * @return                      <EMBED CLASS='external-html' DATA-FILE-ID=TN_HASVAL_RET2>
     * @see                         StrFilter
     */
    @LinkJavaSource(handle="HasAndTest", name="hasValue")
    @LinkJavaSource(handle="AttrRegEx", entity=FIELD, name="KEY_VALUE_REGEX")
    public Map.Entry<String, String> hasValue
        (Predicate<String> attributeValueTest, boolean retainQuotes, boolean preserveKeysCase)
    { return HasAndTest.hasValue(this, attributeValueTest, retainQuotes, preserveKeysCase); }


    // ********************************************************************************************
    // ********************************************************************************************
    // getInstance()
    // ********************************************************************************************
    // ********************************************************************************************


    /**
     * <EMBED CLASS='external-html' DATA-FILE-ID=TN_GETINST_DESC>
     * @param tok Any valid HTML tag.
     * @param openOrClosed <EMBED CLASS='external-html' DATA-FILE-ID=TN_GETINST_OOC>
     * @return An instance of this class
     * 
     * @throws IllegalArgumentException If parameter {@code TC openOrClose} is {@code null} or
     * {@code TC.Both}
     * 
     * @throws HTMLTokException If the parameter {@code String tok} is not a valid HTML-tag
     * 
     * @throws SingletonException If the token requested is a {@code singleton} (self-closing) tag,
     * but the Tag-Criteria {@code 'TC'} parameter is requesting a closing-version of the tag.
     * 
     * @see HTMLTags#hasTag(String, TC)
     * @see HTMLTags#isSingleton(String)
     */
    public static TagNode getInstance(String tok, TC openOrClosed)
    {
        if (openOrClosed == null)
            throw new NullPointerException("The value of openOrClosed cannot be null.");

        if (openOrClosed == TC.Both)
            throw new IllegalArgumentException("The value of openOrClosed cannot be TC.Both.");

        if (HTMLTags.isSingleton(tok) && (openOrClosed == TC.ClosingTags))

            throw new SingletonException(
                "The value of openOrClosed is TC.ClosingTags, but unfortunately you have asked " +
                "for a [" + tok + "] HTML element, which is a singleton element, and therefore " +
                "cannot have a closing-tag instance."
            );

        TagNode ret = HTMLTags.hasTag(tok, openOrClosed);

        if (ret == null)
            throw new HTMLTokException
                ("The HTML-Tag provided isn't valid!\ntok: " + tok + "\nTC: " + openOrClosed);

        return ret;
    }


    // ********************************************************************************************
    // ********************************************************************************************
    // Methods for "CSS Classes"
    // ********************************************************************************************
    // ********************************************************************************************


    /**
     * Convenience Method.
     * <BR />Invokes: {@link #cssClasses()}
     * <BR />Catches-Exception
     */
    public Stream<String> cssClassesNOCSE()
    { try { return cssClasses(); } catch (CSSStrException e) { return Stream.empty(); } }

    /**
     * <EMBED CLASS='external-html' DATA-FILE-ID=TN_CSS_CL_DESC>
     * @return                  <EMBED CLASS='external-html' DATA-FILE-ID=TN_CSS_CL_RET>
     *                          <EMBED CLASS='external-html' DATA-FILE-ID=STRMCNVT>
     * @throws CSSStrException  <EMBED CLASS='external-html' DATA-FILE-ID=TN_CSS_CL_CSSSE>
     * @see                     #cssClasses()
     * @see                     #AV(String)
     * @see                     StringParse#WHITE_SPACE_REGEX
     * @see                     CSSStrException#check(Stream)
     */
    @LinkJavaSource(handle="ClassIDStyle", name="cssClasses")
    public Stream<String> cssClasses()
    { return ClassIDStyle.cssClasses(this); }

    /**
     * <EMBED CLASS='external-html' DATA-FILE-ID=TN_SET_CSS_CL_DESC>
     * @param quote             <EMBED CLASS='external-html' DATA-FILE-ID=TGND_QUOTE_EXPL>
     * @param appendOrClobber   <EMBED CLASS='external-html' DATA-FILE-ID=TN_SET_CSS_CL_AOC>
     * @param cssClasses        <EMBED CLASS='external-html' DATA-FILE-ID=TN_SET_CSS_CL_CCL>
     * @return                  <EMBED CLASS='external-html' DATA-FILE-ID=TN_SET_CSS_CL_RET>
     * 
     * @throws CSSStrException This exception shall throw if any of the {@code 'cssClasses'} in the
     * var-args {@code String...} parameter do not meet the HTML 5 CSS {@code Class} naming rules.
     * 
     * @throws ClosingTagNodeException  <EMBED CLASS=external-html DATA-FILE-ID=CTNEX>
     * @throws QuotesException          <EMBED CLASS=external-html DATA-FILE-ID=TN_SET_CSS_CL_QEX>
     * @see                             CSSStrException#check(String[])
     * @see                             CSSStrException#VALID_CSS_CLASS_OR_NAME_TOKEN
     * @see                             #appendToAV(String, String, boolean, SD)
     * @see                             #setAV(String, String, SD)
     */
    @LinkJavaSource(handle="ClassIDStyle", name="setCSSClasses")
    public TagNode setCSSClasses(SD quote, boolean appendOrClobber, String... cssClasses)
    { return ClassIDStyle.setCSSClasses(this, quote, appendOrClobber, cssClasses); }

    /**
     * <EMBED CLASS='external-html' DATA-FILE-ID=TN_APD_CSS_CL_DESC>
     * @param cssClass This is the CSS-{@code Class} name that is being inserted into
     * {@code 'this'} instance of {@code TagNode}
     * 
     * @param quote                     <EMBED CLASS=external-html DATA-FILE-ID=TGND_QUOTE_EXPL>
     * @return                          A new {@code TagNode} with updated CSS {@code Class} Name(s)
     * @throws CSSStrException          <EMBED CLASS=external-html DATA-FILE-ID=TN_APD_CSS_CL_CSSSE>
     * @throws ClosingTagNodeException  <EMBED CLASS=external-html DATA-FILE-ID=CTNEX>
     * @throws QuotesException          <EMBED CLASS=external-html DATA-FILE-ID=TN_APD_CSS_CL_QEX>
     * @see                             CSSStrException#check(String[])
     * @see                             #setAV(String, String, SD)
     * @see                             #appendToAV(String, String, boolean, SD)
     */
    @LinkJavaSource(handle="ClassIDStyle", name="appendCSSClass")
    public TagNode appendCSSClass(String cssClass, SD quote)
    { return ClassIDStyle.appendCSSClass(this, cssClass, quote); }


    // ********************************************************************************************
    // ********************************************************************************************
    // Methods for "CSS Style"
    // ********************************************************************************************
    // ********************************************************************************************


    /**
     * <EMBED CLASS='external-html' DATA-FILE-ID=TN_CSS_STYLE_DESC>
     * <EMBED CLASS='external-html' DATA-FILE-ID=TN_CSS_STYLE_DESCEX>
     * @return <EMBED CLASS='external-html' DATA-FILE-ID=TN_CSS_STYLE_RET>
     */
    @LinkJavaSource(handle="ClassIDStyle", name="cssStyle")
    @LinkJavaSource(handle="AttrRegEx", entity=FIELD, name="CSS_INLINE_STYLE_REGEX")
    public Properties cssStyle()
    { return ClassIDStyle.cssStyle(this); }

    /**
     * <EMBED CLASS='external-html' DATA-FILE-ID=TN_SET_CSS_STY_DESC>
     * @param p                         <EMBED CLASS=external-html DATA-FILE-ID=TN_SET_CSS_STY_P>
     * @param quote                     <EMBED CLASS=external-html DATA-FILE-ID=TGND_QUOTE_EXPL>
     * @param appendOrClobber           <EMBED CLASS=external-html DATA-FILE-ID=TN_SET_CSS_STY_AOC>
     * @return                          <EMBED CLASS=external-html DATA-FILE-ID=TN_SET_CSS_STY_RET>
     * @throws ClosingTagNodeException  <EMBED CLASS=external-html DATA-FILE-ID=CTNEX>
     * @throws CSSStrException          If there is an invalid CSS Style Property Name.
     * 
     * @throws QuotesException If the style-element's quotation marks are incompatible with any
     * and all quotation marks employed by the style-element definitions.
     * 
     * @see CSSStrException#VALID_CSS_CLASS_OR_NAME_TOKEN
     * @see #appendToAV(String, String, boolean, SD)
     * @see #setAV(String, String, SD)
     */
    @LinkJavaSource(handle="ClassIDStyle", name="setCSSStyle")
    public TagNode setCSSStyle(Properties p, SD quote, boolean appendOrClobber)
    { return ClassIDStyle.setCSSStyle(this, p, quote, appendOrClobber); }


    // ********************************************************************************************
    // ********************************************************************************************
    // Methods for "CSS ID"
    // ********************************************************************************************
    // ********************************************************************************************


    /**
     * Convenience Method.
     * <BR />Invokes: {@link #AV(String)}
     * <BR />Passes: {@code String "id"}, the CSS-ID attribute-<B STYLE='color: red;'>name</B>
     */
    public String getID()
    {
        String id = AV("ID");
        return (id == null) ? null : id.trim();
    }

    /**
     * This merely sets the current CSS {@code 'ID'} Attribute <B STYLE='color: red;'>Value</B>.
     *
     * @param id This is the new CSS {@code 'ID'} attribute-<B STYLE='color: red;'>value</B> that
     * the user would like applied to {@code 'this'} instance of {@code TagNode}.
     * 
     * @param quote <EMBED CLASS='external-html' DATA-FILE-ID=TGND_QUOTE_EXPL>
     *
     * @return Returns a new instance of {@code TagNode} that has an updated {@code 'ID'} 
     * attribute-<B STYLE='color: red;'>value</B>.
     * 
     * @throws IllegalArgumentException This exception shall throw if an invalid
     * {@code String}-token has been passed to parameter {@code 'id'}.
     *
     * <BR /><BR /><B>BYPASS NOTE:</B> If the user would like to bypass this exception-check, for
     * instance because he / she is using a CSS Pre-Processor, then applying the general-purpose
     * method {@code TagNode.setAV("id", "some-new-id")} ought to suffice.  This other method will
     * not apply validity checking, beyond scanning for the usual "quotes-within-quotes" problems,
     * which is always disallowed.
     *
     * @throws ClosingTagNodeException <EMBED CLASS='external-html' DATA-FILE-ID=CTNEX>
     * 
     * @see CSSStrException#VALID_CSS_CLASS_OR_NAME_TOKEN
     * @see #setAV(String, String, SD)
     */
    public TagNode setID(String id, SD quote)
    {
        if (! CSSStrException.VALID_CSS_CLASS_OR_NAME_TOKEN_PRED.test(id))

            throw new IllegalArgumentException(
                "The id parameter provide: [" + id + "], does not conform to the standard CSS " +
                "Names.\nEither try using the generic TagNode.setAV(\"id\", yourNewId, quote); " +
                "method to bypass this check, or change the value passed to the 'id' parameter " +
                "here."
            );

        return setAV("id", id.trim(), quote);
    }


    // ********************************************************************************************
    // ********************************************************************************************
    // Attributes that begin with "data-..."
    // ********************************************************************************************
    // ********************************************************************************************


    /**
     * Convenience Method.
     * <BR />See Documentation: {@link #AV(String)}
     * <BR />Passes: {@code "data-"} prepended to parameter {@code 'dataName'} for the
     * attribute-<B STYLE='color:red'>name</B>
     */
    @LinkJavaSource(handle="GetSetAttr", name="AV")
    public String dataAV(String dataName)
    { return GetSetAttr.AV(this, "data-" + dataName, false); }

    /**
     * <EMBED CLASS='external-html' DATA-FILE-ID=TN_REM_DATTR_DESC>
     * @return                          <EMBED CLASS=external-html DATA-FILE-ID=TN_REM_DATTR_RET>
     * @throws ClosingTagNodeException  <EMBED CLASS=external-html DATA-FILE-ID=TN_REM_DATTR_CTNEX>
     */
    @LinkJavaSource(handle="RemoveAttributes", name="removeAttributes")
    public TagNode removeDataAttributes() 
    {
        return RemoveAttributes.removeAttributes
            (this, (String attr) -> ! StrCmpr.startsWithIgnoreCase(attr, "data-") );
    }

    /**
     * Convenience Method.
     * <BR />See Documentation: {@link #getDataAV(boolean)}
     * <BR />Attribute-<B STYLE='color: red;'>names</B> will be in lower-case
     */
    @LinkJavaSource(handle="DataAttributes", name="getDataAV")
    @LinkJavaSource(handle="AttrRegEx", entity=FIELD, name="DATA_ATTRIBUTE_REGEX")
    public Properties getDataAV()
    { return DataAttributes.getDataAV(this, false); }

    /**
     * <EMBED CLASS='external-html' DATA-FILE-ID=TN_GET_DATA_AV_DESC>
     * @param preserveKeysCase  <EMBED CLASS='external-html' DATA-FILE-ID=TN_GET_DATA_AV_PAR>
     *                          <EMBED CLASS='external-html' DATA-FILE-ID=TAGNODE_PRESERVE_C>
     * @return                  <EMBED CLASS='external-html' DATA-FILE-ID=TN_GET_DATA_AV_RET>
     */
    @LinkJavaSource(handle="DataAttributes", name="getDataAV")
    @LinkJavaSource(handle="AttrRegEx", entity=FIELD, name="DATA_ATTRIBUTE_REGEX")
    public Properties getDataAV(boolean preserveKeysCase) 
    { return DataAttributes.getDataAV(this, preserveKeysCase); }

    /**
     * Convenience Method.
     * <BR />See Documentation: {@link #getDataAN(boolean)}
     * <BR />Attribute-<B STYLE='color: red;'>names</B> will be in lower-case
     */
    public Stream<String> getDataAN()
    { return DataAttributes.getDataAN(this, false); }

    /**
     * <EMBED CLASS='external-html' DATA-FILE-ID=TN_GET_DATA_AN_DESC>
     * @param preserveKeysCase  <EMBED CLASS='external-html' DATA-FILE-ID=TN_GET_DATA_AN_PAR>
     *                          <EMBED CLASS='external-html' DATA-FILE-ID=TAGNODE_PRESERVE_C>
     * @return                  <EMBED CLASS='external-html' DATA-FILE-ID=TN_GET_DATA_AN_RET>
     *                          <EMBED CLASS='external-html' DATA-FILE-ID=STRMCNVT>
     */
    @LinkJavaSource(handle="DataAttributes", name="getDataAN")
    @LinkJavaSource(handle="AttrRegEx", entity=FIELD, name="DATA_ATTRIBUTE_REGEX")
    public Stream<String> getDataAN(boolean preserveKeysCase) 
    { return DataAttributes.getDataAN(this, preserveKeysCase); }


    // ********************************************************************************************
    // ********************************************************************************************
    // Java Methods
    // ********************************************************************************************
    // ********************************************************************************************


    /**
     * <EMBED CLASS='external-html' DATA-FILE-ID=TN_TOSTR_AV_DESC>
     * @return <EMBED CLASS='external-html' DATA-FILE-ID=TN_TOSTR_AV_RET>
     * @see HTMLNode#toString()
     */
    @LinkJavaSource(handle="GeneralPurpose", name="toStringAV")
    public String toStringAV()
    { return GeneralPurpose.toStringAV(this); }

    /**
     * Java's {@code interface Cloneable} requirements.  This instantiates a new {@code TagNode}
     * with identical <SPAN STYLE='color: red;'>{@code String str}</SPAN> fields, and also
     * identical <SPAN STYLE='color: red;'>{@code boolean isClosing}</SPAN> and
     * <SPAN STYLE='color: red;'>{@code String tok}</SPAN> fields.
     * 
     * @return A new {@code TagNode} whose internal fields are identical to this one.
     */
    public TagNode clone() { return new TagNode(str); }

    /**
     * <EMBED CLASS='external-html' DATA-FILE-ID=TN_COMPARETO_DESC>
     * @param n Any other {@code TagNode} to be compared to {@code 'this' TagNode}
     * @return An integer that fulfils Java's {@code Comparable} interface-method requirements.
     */
    public int compareTo(TagNode n)
    {
        // Utilize the standard "String.compare(String)" method with the '.tok' string field.
        // All 'tok' fields are stored as lower-case strings.
        int compare1 = this.tok.compareTo(n.tok);

        // Comparison #1 will be non-zero if the two TagNode's being compared had different
        // .tok fields
        if (compare1 != 0) return compare1;

        // If the '.tok' fields were the same, use the 'isClosing' field for comparison instead.
        // This comparison will only be used if they are different.
        if (this.isClosing != n.isClosing) return (this.isClosing == false) ? -1 : 1;
    
        // Finally try using the entire element '.str' String field, instead.  
        return this.str.length() - n.str.length();
    }


    // ********************************************************************************************
    // ********************************************************************************************
    // toUpperCase 
    // ********************************************************************************************
    // ********************************************************************************************


    /**
     * <EMBED CLASS=defs DATA-CASE=Upper DATA-CAPITAL="">
     * <EMBED CLASS='external-html' DATA-FILE-ID=TN_TO_UPLOW_1_DESC>
     * @param justTag_Or_TagAndAttributeNames 
     * <EMBED CLASS='external-html' DATA-FILE-ID=TN_TO_UPLOW_1_PARAM>
     * @return <EMBED CLASS='external-html' DATA-FILE-ID=TN_TO_UPLOW_1_RET>
     */
    @LinkJavaSource(handle="CaseChange", name="toCaseInternal", paramCount=3)
    public TagNode toUpperCase(boolean justTag_Or_TagAndAttributeNames)
    {
        return CaseChange.toCaseInternal
            (this, justTag_Or_TagAndAttributeNames, String::toUpperCase);
    }

    /**
     * Convenience Method.
     * <BR />See Documentation: {@link #toUpperCase(boolean, Predicate)}
     * <BR />Passes: {@code StrCmpr.equalsXOR_CI(attrName, attributeNames)}
     * @see StrCmpr#equalsXOR_CI(String, String...)
     */
    @LinkJavaSource(handle="CaseChange", name="toCaseInternal", paramCount=4)
    @LinkJavaSource(handle="AttrRegEx", entity=FIELD, name="KEY_VALUE_REGEX")
    public TagNode toUpperCase(boolean tag, String... attributeNames)
    {
        return CaseChange.toCaseInternal(
            this,
            tag,
            (String attrName) -> StrCmpr.equalsXOR_CI(attrName, attributeNames),
            String::toUpperCase
        );
    }

    /**
     * <EMBED CLASS=defs DATA-CASE=Upper DATA-CAPITAL="">
     * <EMBED CLASS='external-html' DATA-FILE-ID=TN_TO_UPLOW_2_DESC>
     * @param tag           Indicates whether or not the Tag-Name should be capitalized
     * @param attrNameTest  <EMBED CLASS='external-html' DATA-FILE-ID=TN_TO_UPLOW_2_PARAM>
     * @return              <EMBED CLASS='external-html' DATA-FILE-ID=TN_TO_UPLOW_2_RET>
     */
    @LinkJavaSource(handle="CaseChange", name="toCaseInternal", paramCount=4)
    @LinkJavaSource(handle="AttrRegEx", entity=FIELD, name="KEY_VALUE_REGEX")
    public TagNode toUpperCase(boolean tag, Predicate<String> attrNameTest)
    { return CaseChange.toCaseInternal(this, tag, attrNameTest, String::toUpperCase); }


    // ********************************************************************************************
    // ********************************************************************************************
    // toLowerCase 
    // ********************************************************************************************
    // ********************************************************************************************


    /**
     * <EMBED CLASS=defs DATA-CASE=Lower DATA-CAPITAL="de-">
     * <EMBED CLASS='external-html' DATA-FILE-ID=TN_TO_UPLOW_1_DESC>
     * @param justTag_Or_TagAndAttributeNames 
     * <EMBED CLASS='external-html' DATA-FILE-ID=TN_TO_UPLOW_1_PARAM>
     * @return <EMBED CLASS='external-html' DATA-FILE-ID=TN_TO_UPLOW_1_RET>
     */
    @LinkJavaSource(handle="CaseChange", name="toCaseInternal", paramCount=3)
    public TagNode toLowerCase(boolean justTag_Or_TagAndAttributeNames)
    {
        return CaseChange.toCaseInternal
            (this, justTag_Or_TagAndAttributeNames, String::toLowerCase);
    }

    /**
     * Convenience Method.
     * <BR />See Documentation: {@link #toLowerCase(boolean, Predicate)}
     * <BR />Passes: {@code StrCmpr.equalsXOR_CI(attrName, attributeNames)}
     * @see StrCmpr#equalsXOR_CI(String, String...)
     */
    @LinkJavaSource(handle="CaseChange", name="toCaseInternal", paramCount=4)
    @LinkJavaSource(handle="AttrRegEx", entity=FIELD, name="KEY_VALUE_REGEX")
    public TagNode toLowerCase(boolean tag, String... attributeNames)
    {
        return CaseChange.toCaseInternal(
            this,
            tag,
            (String attrName) -> StrCmpr.equalsXOR_CI(attrName, attributeNames),
            String::toLowerCase
        );
    }

    /**
     * <EMBED CLASS=defs DATA-CASE=Lower DATA-CAPITAL="de-">
     * <EMBED CLASS='external-html' DATA-FILE-ID=TN_TO_UPLOW_2_DESC>
     * @param tag           Indicates whether or not the Tag-Name should be decapitalized
     * @param attrNameTest  <EMBED CLASS='external-html' DATA-FILE-ID=TN_TO_UPLOW_2_PARAM>
     * @return              <EMBED CLASS='external-html' DATA-FILE-ID=TN_TO_UPLOW_2_RET>
     */
    @LinkJavaSource(handle="CaseChange", name="toCaseInternal", paramCount=4)
    @LinkJavaSource(handle="AttrRegEx", entity=FIELD, name="KEY_VALUE_REGEX")
    public TagNode toLowerCase(boolean tag, Predicate<String> attrNameTest)
    { return CaseChange.toCaseInternal(this, tag, attrNameTest, String::toLowerCase); }


    // ********************************************************************************************
    // ********************************************************************************************
    // Attribute-Value Quotation-Marks - REMOVE
    // ********************************************************************************************
    // ********************************************************************************************


    /**
     * Convenience Method.
     * <BR />See Documentation: {@link #removeAVQuotes(Predicate)}
     * <BR />Removes Quotation-Marks from <B STYLE='color: red;'>Value</B> whose Inner-Tag 
     * <B STYLE='color: red;'>Name</B> matches {@code 'attributeName'}
     */
    @LinkJavaSource(handle="QuotationMarks", name="removeAVQuotes")
    public TagNode removeAVQuotes(String attributeName)
    {
        return QuotationMarks.removeAVQuotes
            (this, (String attr) -> attr.equalsIgnoreCase(attributeName));
    }

    /**
     * Convenience Method.
     * <BR />See Documentation: {@link #removeAVQuotes(Predicate)}
     * <BR />Removes Quotation-Marks from all Inner-Tag <B STYLE='color: red;'>Values</B>
     */
    @LinkJavaSource(handle="QuotationMarks", name="removeAVQuotes")
    public TagNode removeAllAVQuotes()
    { return QuotationMarks.removeAVQuotes(this, (String attr) -> true); }

    /**
     * <EMBED CLASS='external-html' DATA-FILE-ID=TN_REM_QUOTES_DESC>
     * @param attrNameTest      <EMBED CLASS='external-html' DATA-FILE-ID=TN_REM_QUOTES_PARAM>
     * @return                  <EMBED CLASS='external-html' DATA-FILE-ID=TN_REM_QUOTES_RET>
     * @throws QuotesException  If the resulting <CODE>TagNode</CODE> contains Quotation-Errors
     */
    @LinkJavaSource(handle="QuotationMarks", name="removeAVQuotes")
    public TagNode removeAVQuotes(Predicate<String> attrNameTest)
    { return QuotationMarks.removeAVQuotes(this, attrNameTest); }


    // ********************************************************************************************
    // ********************************************************************************************
    // Attribute-Value Quotation-Marks - SET
    // ********************************************************************************************
    // ********************************************************************************************


    /**
     * Convenience Method.
     * <BR />See Documentation: {@link #setAVQuotes(Predicate, SD)}}
     * <BR />Set Quotation-Marks for the Attribute whose <B STYLE='color: red;'>Name</B> matches
     * {@code 'attributeName'}
     */
    @LinkJavaSource(handle="QuotationMarks", name="setAVQuotes")
    public TagNode setAVQuotes(String attributeName, SD quote)
    {
        return QuotationMarks.setAVQuotes
            (this, (String attr) -> attr.equalsIgnoreCase(attributeName), quote);
    }

    /**
     * Convenience Method.
     * <BR />See Documentation: {@link #setAVQuotes(Predicate, SD)}}
     * <BR />Set the Quotation-Marks which are used with all Attribute's contained by
     * {@code 'this'} Tag.
     */
    @LinkJavaSource(handle="QuotationMarks", name="setAVQuotes")
    public TagNode setAllAVQuotes(SD quote)
    { return QuotationMarks.setAVQuotes(this, (String attr) -> true, quote); }

    /**
     * <EMBED CLASS='external-html' DATA-FILE-ID=TN_SET_QUOTES_DESC>
     * @param attrNameTest          <EMBED CLASS='external-html' DATA-FILE-ID=TN_SET_QUOTES_PARAM>
     * @param quote                 The new Quotation-Mark to apply
     * @return                      <EMBED CLASS='external-html' DATA-FILE-ID=TN_SET_QUOTES_RET>
     * @throws QuotesException      If the resulting <CODE>TagNode</CODE> contains Quotation-Errors
     * @throws NullPointerException If either parameter is passed null.
     */
    @LinkJavaSource(handle="QuotationMarks", name="setAVQuotes")
    public TagNode setAVQuotes(Predicate<String> attrNameTest, SD quote)
    { return QuotationMarks.setAVQuotes(this, attrNameTest, quote); }


    // ********************************************************************************************
    // ********************************************************************************************
    // Attribute-Value Quotation-Marks - GET
    // ********************************************************************************************
    // ********************************************************************************************

}