package Torello.HTML.NodeSearch;

import java.util.Vector;
import java.util.function.Predicate;
import java.util.regex.Pattern;

import Torello.HTML.*;
import Torello.Java.StrFilter;

/**
 * A functional-interface / lambda-target, and several {@code static}-builders for generating
 * instances of them, which extends {@code java.util.function.Predicate} and encapsulates
 * search-criteria into a <CODE>Predicate&lt;{@link TagNode}&gt;</CODE>
 * 
 * <BR /><BR /><EMBED CLASS='external-html' DATA-FILE-ID=AVT>
 */
@FunctionalInterface
public interface AVT extends Predicate<TagNode>, java.io.Serializable
{
    /** <EMBED CLASS='external-html' DATA-FILE-ID=SVUIDFI>  */
    public static final long serialVersionUID = 1;

    // ******************************************************************************************
    // Functional-Interface Method
    // ******************************************************************************************

    /**
     * <B><SPAN STYLE="color: red;">FUNCTIONAL-INTERFACE BOOLEAN METHOD:</SPAN></B> This is the 
     * method that fulfils this {@code functional-interface 'test'} method.
     *
     * @param tn This method will be called - once for each {@code TagNode} found inside of a 
     * vectorized HTML page.
     * 
     * @return If the {@code TagNode} meets the test's "inclusion requirements", then this method
     * should return {@code TRUE}.
     */
    public boolean test(TagNode tn);

    // ******************************************************************************************
    // TextComparitor factory builders
    // ******************************************************************************************

    /**
     * This is a {@code static} factory method that generates {@code AVT-Predicate's}
     * ({@code Predicate<TagNode>}).  It saves the user of typing the lambda information by hand,
     * and does a validation check too.  The primary use of this class is that the results of one
     * factory method may be "AND-chained" or "OR-chained" with another to make search requirements
     * more specific.
     *
     * @param innerTag This also goes by the term "attribute" in many HTML specifications.  It is
     * the <B STYLE="color: red;">name</B> of the attribute, not it's
     * <B STYLE="color: red;">value</B>. The <B STYLE="color: red;">value</B> will be found (if the
     * {@code TagNode} contains this attribute), and the parameter {@code 'TextComparitor'} will be
     * used to compare this <B STYLE="color: red;">value</B> - <I>dependent upon which
     * {@code 'TextComparitor'} is used</I> against the Compare-Strings
     *
     * @param tc This may be any of the listed {@code TextComparitor's} in the class.  There are
     * quite a few "pre-defined" {@code static} members in the {@link TextComparitor} class.  There
     * are many that have both long names, and abbreviated names which can be interchangeably used
     * for readability purposes.
     * 
     * @param compareStr These are passed to the {@code 'TextComparitor'} when using to perform
     * tests on the attribute <B STYLE="color: red;">value</B>.
     *
     * @return <EMBED CLASS='external-html' DATA-FILE-ID=RETCMP1>
     * 
     * @see ARGCHECK#innerTag(String)
     * @see ARGCHECK#TC(TextComparitor, String[])
     * @see TagNode#AV(String)
     * @see TextComparitor#test(String, String[])
     *
     * @throws InnerTagKeyException <EMBED CLASS='external-html' DATA-FILE-ID=ITKEYEX>
     * @throws NullPointerException If any of the provided input reference parameters are null.
     */
    public static AVT cmp(String innerTag, TextComparitor tc, String... compareStr)
    {
        // FAIL-FAST: It is helpful for the user to test the data before building the Predicate.
        // If these tests fail, the returned predicate would absolutely fail.

        final String innerTagLC = ARGCHECK.innerTag(innerTag);
        ARGCHECK.TC(tc, compareStr);

        // Minimum length for field TagNode.str to have before it could possible contain the attribute
        // Obviously, the TagNode would have to have a min-length that includes the
        // attribute-name length + '< ' and '>'

        final int MIN_LEN = innerTag.length() + 3;

        // Java's "Lambda-Expression" Syntax (like an "anonymous method").
        // AVT extends functional-interface Predicate<TagNode>
        return (TagNode tn) ->
        {
            // This eliminates testing any TagNode that simply COULD NOT contain the
            // specified attribute.  (an optimization)

            if (tn.isClosing || (tn.str.length() <= (tn.tok.length() + MIN_LEN))) return false;

            // Retrieve the value of the requested "inner-tag" (HTML Attribute) Key-Value Pair
            // from the input HTML-Element (TagNode)

            String itv = tn.AV(innerTagLC);
                // REG-EX MATCHER, MORE EXPENSIVE
    
            // If the innerTag's value is null, then the inner-tag was not a key-value 
            // found inside the TagNode: return false.
            // Otherwise return the 'tc' test-results on that value using the named 'tc' 
            // comparison on the compare-strings.

            return (itv == null) ? false : tc.test(itv, compareStr);  
        };
    }

    /**
     * <EMBED CLASS='external-html' DATA-FILE-ID=CMPKIITNF1>
     * 
     * @param innerTag This also goes by the term "attribute" in many HTML specifications.  It is
     * the <B STYLE="color: red;">name</B> of the attribute, not it's
     * <B STYLE="color: red;">value</B>. The <B STYLE="color: red;">value</B> will be found (if the
     * {@code TagNode} contains this attribute), and the parameter {@link TextComparitor} will be
     * used to compare this <B STYLE="color: red;">value</B> - <I>dependent upon which
     * {@code 'TextComparitor'} is used</I> against the Compare-{@code String's}
     *
     * @param tc This may be any of the listed {@code TextComparitor's} in the class.  There are
     * quite a few "pre-defined" {@code static} members in the {@code TextComparitor} class.  There
     * are many that have both long names, and abbreviated names which can be interchangeably used
     * for readability purposes.
     *
     * @param compareStr These are passed to the {@code 'TextComparitor'}  to perform tests on the
     * attribute <B STYLE="color: red;">value</B>.
     *
     * @return An instance of {@code 'AVT'} that can be passed to the NodeSearch classes
     * search-methods via any one of the methods that accepts a {@code Predicate<TagNode>} as a
     * parameter in the search criteria.
     *
     * @see #cmp(String, TextComparitor, String[])
     *
     * @throws InnerTagKeyException <EMBED CLASS='external-html' DATA-FILE-ID=ITKEYEX>
     * @throws NullPointerException If any of the provided input reference parameters are null.
     */
    public static AVT cmpKIITNF(String innerTag, TextComparitor tc, String... compareStr)
    {
        // FAIL-FAST: It is helpful for the user to test the data before building the Predicate.
        // If these tests fail, the returned predicate would absolutely fail.

        final String innerTagLC = ARGCHECK.innerTag(innerTag);
        ARGCHECK.TC(tc, compareStr);

        // Java's "Lambda-Expression" Syntax (like an "anonymous method").
        // AVT extends functional-interface Predicate<TagNode>

        return (TagNode tn) ->
        {
            // This eliminates testing any TagNode that simply COULD NOT contain
            // attributes.  (an optimization)
            //
            // KIITNF -> Empty Opening HTML TagNode Elements cannot be eliminated!
            // HOWEVER, Closing TagNodes are never included

            if (tn.isClosing) return false;

            // Retrieve the value of the requested "inner-tag" (HTML Attribute) Key-Value Pair
            // from the input HTML-Element (TagNode)

            String itv = tn.AV(innerTagLC);
                // REG-EX MATCHER, MORE EXPENSIVE

            // If the innerTag's value is null, then the inner-tag was not a key-value pair
            // found inside the TagNode.
            //
            // BECAUSE the user requested to "Keep If Inner-Tag Not Found", we must return TRUE
            //      in that case.
            //      In Java '||' uses short-circuit boolean-evaluation, while '|' requires
            //      full-evaluation.
            //
            // OTHERWISE return the 'tc' test-results on that value using the named 'tc' comparison
            //      on the compare-strings.

            return (itv == null) || tc.test(itv, compareStr);
        };
    }

    // ********************************************************************************************
    // Regular-Expression (Pattern) factory builders.
    // ********************************************************************************************

    /**
     * This is a {@code static} factory method that generates {@code AVT-Predicate's}
     * ({@code Predicate<TagNode>}).  It saves the user of typing the lambda information by hand,
     * and does a validation check too.  The primary use of this class is that the results of one
     * factory method may be "AND-chained" or "OR-chained" with another to make search requirements
     * more specific.
     *
     * @param innerTag This also goes by the term "attribute" in many HTML specifications.  It is
     * the <B STYLE="color: red;">name</B> of the attribute, not it's
     * <B STYLE="color: red;">value</B>. The <B STYLE="color: red;">value</B> will be found (if the
     * {@code TagNode} contains this attribute), and then tested using the Regular-Expression
     * {@code p.matcher(tag_value).find()} method.
     *
     * @param p This may be any regular expression {@code Pattern}.  This {@code Pattern} will be
     * executed against the <B STYLE="color: red;">value</B> of the inner-tag specified by
     * parameter {@code 'innerTag'}.
     *
     * @return <EMBED CLASS='external-html' DATA-FILE-ID=RETCMP2>
     *
     * @see ARGCHECK#innerTag(String)
     * @see ARGCHECK#REGEX(Pattern)
     * @see TagNode#AV(String)
     *
     * @throws InnerTagKeyException <EMBED CLASS='external-html' DATA-FILE-ID=ITKEYEX>
     * @throws NullPointerException If any of the provided input reference parameters are null.
     */
    public static AVT cmp(String innerTag, Pattern p)
    {
        // FAIL-FAST: It is helpful for the user to test the data before building the Predicate.
        // If these tests fail, the returned predicate would absolutely fail.

        final String            innerTagLC  = ARGCHECK.innerTag(innerTag);
        final Predicate<String> pred        = ARGCHECK.REGEX(p);

        // Minimum length for field TagNode.str to have before it could possible contain the attribute
        // Obviously, the TagNode would have to have a min-length that includes the attribute-name
        // length + '< ' and '>'

        final int MIN_LEN = innerTag.length() + 3;

        // Java's "Lambda-Expression" Syntax (like an "anonymous method").
        // AVT extends functional-interface Predicate<TagNode>

        return (TagNode tn) ->
        {
            // This eliminates testing any TagNode that simply COULD NOT contain the
            // attribute.  (an optimization)

            if (tn.isClosing || (tn.str.length() <= (tn.tok.length() + MIN_LEN))) return false;

            // Retrieve the value of the requested "inner-tag" (HTML Attribute) Key-Value Pair
            // from the input HTML-Element (TagNode)
            //
            // REG-EX MATCHER, MORE EXPENSIVE

            String itv = tn.AV(innerTagLC);

            // If the innerTag's value is null, then the inner-tag was not a key-value pair
            // found inside the TagNode: return false.
            // Otherwise return the results of running the Regular-Expression matcher using the
            // input 'Pattern' instance.

            return (itv == null) ? false : pred.test(itv);
        };
    }

    /**
     * This is a {@code static} factory method that generates {@code AVT-Predicate's}
     * ({@code Predicate<TagNode>}).  It saves the user of typing the lambda information by hand,
     * and does a validation check too.  The primary use of this class is that the results of one
     * factory method may be "AND-chained" or "OR-chained" with another to make search requirements
     * more specific.
     *
     * @param innerTag This also goes by the term "attribute" in many HTML specifications.  It is
     * the <B STYLE="color: red;">name</B> of the attribute, not it's
     * <B STYLE="color: red;">value</B>. The <B STYLE="color: red;">value</B> will be found (if the
     * {@code TagNode} contains this attribute), and then tested using the Regular-Expression
     * {@code p.matcher(tag_value).find()} method.
     *
     * @param p This may be any regular expression {@code Pattern}.  This {@code Pattern} will be
     * executed against the <B STYLE="color: red;">value</B> of the inner-tag specified by
     * parameter {@code 'innerTag'}.
     *
     * @param keepOnMatch There may be times when it is necessary to specify that a
     * Regular-Expression match should cause the search-filter to reject a {@code TagNode}, rather
     * than keeping it as a search-result match.  In this case, the programmer can utilize this
     * variable to indicate whether matches should cause this method to return {@code TRUE} or
     * {@code FALSE}.  If this variable is set to {@code FALSE}, then the {@code Predicate<TagNode>}
     * that is generated will return {@code FALSE}, whenever the regular-expression matches the
     * Attribute-<B STYLE="color: red;">Value</B>.
     *
     * <BR /><BR /><B><SPAN STYLE="color: red;">DEFAULT BEHAVIOR NOTE:</B></SPAN> The classes and 
     * methods in this Node Search Package that accept regular-expressions as search-parameters
     * will always treat a match to indicate that the {@code TagNode} (or {@code TextNode}) in
     * question <B><I>has passed</I></B> the search-filter criteria.  This method, therefore,
     * provides a way to bypass this default behavior.
     *
     * @param keepOnNull This parameter allows the user to specify whether the absence of an HTML
     * Inner-Tag should indicate that the TagNode being tested should pass or fail (keep or
     * reject) the search-filter criteria.
     *
     * <BR /><BR /><B><SPAN STYLE="color: red;">DEFAULT BEHAVIOR NOTE:</B></SPAN> The default 
     * filter-results for the search classes and search methods of the Node-Search Package are such
     * that if an inner-tag is simply not available ... or 'not present' within an HTML Element,
     * then that element <I><B>will not be included</I></B> in the search results for that class or
     * method. <B><I>By using this particular {@code AVT} factory-method, a programmer can by-pass
     * that default behavior.</I></B>
     *
     * @return An instance of {@code 'AVT'} that can be passed to the NodeSearch classes
     * search-methods via any one of the methods that accepts a {@code Predicate<TagNode>} as a
     * parameter in the search criteria.
     *
     * @see ARGCHECK#innerTag(String)
     * @see ARGCHECK#REGEX(Pattern)
     * @see TagNode#AV(String)
     *
     * @throws InnerTagKeyException <EMBED CLASS='external-html' DATA-FILE-ID=ITKEYEX>
     * @throws NullPointerException If any of the provided input reference parameters are null.
     */
    public static AVT cmp
        (String innerTag, Pattern p, final boolean keepOnMatch, final boolean keepOnNull)
    {
        // FAIL-FAST: It is helpful for the user to test the data before building the Predicate.
        // If these tests fail, the returned predicate would absolutely fail.

        final String            innerTagLC  = ARGCHECK.innerTag(innerTag);
        final Predicate<String> pred        = ARGCHECK.REGEX(p);

        // Java's "Lambda-Expression" Syntax (like an "anonymous method").
        // AVT extends functional-interface Predicate<TagNode>

        return (TagNode tn) ->
        {
            // This eliminates testing any TagNode that simply COULD NOT contain 
            // attributes.  (an optimization)
            //
            // keepOnNull -> Empty Opening HTML TagNode Elements cannot be eliminated!
            // HOWEVER,     Closing TagNodes are never included

            if (tn.isClosing) return false;

            // Retrieve the value of the requested "inner-tag" (HTML Attribute) Key-Value Pair
            // from the input HTML-Element (TagNode)
            //
            // REG-EX MATCHER, MORE EXPENSIVE

            String itv = tn.AV(innerTagLC);

            // If the Attribute is simply not present in the HTML Element
            if (itv == null)    return keepOnNull;   

            if (pred.test(itv)) return keepOnMatch;     // if the Regular-Expression succeeded
            else                return ! keepOnMatch;   // If the Regular-Expression failed
        };
    }

    /**
     * <EMBED CLASS='external-html' DATA-FILE-ID=CMPKIITNF2>
     *
     * @param innerTag This also goes by the term "attribute" in many HTML specifications.  It is
     * the <B STYLE="color: red;">name</B> of the attribute, not it's
     * <B STYLE="color: red;">value</B>. The <B STYLE="color: red;">value</B> will be found (if the
     * {@code TagNode} contains this attribute), and then tested using the Regular-Expression
     * {@code p.matcher(tag_value).find()} method.
     *
     * @param p This may be any regular expression {@code Pattern}.  This {@code Pattern} will be
     * executed against the <B STYLE="color: red;">value</B> of the inner-tag specified by
     * parameter {@code 'innerTag'}.
     *
     * @return An instance of {@code 'AVT'} that can be passed to the NodeSearch classes
     * search-methods via any one of the methods that accepts a {@code Predicate<TagNode>} as a
     * parameter in the search parameter-list.
     *
     * @see #cmp(String, Pattern)
     *
     * @throws InnerTagKeyException <EMBED CLASS='external-html' DATA-FILE-ID=ITKEYEX>
     * @throws NullPointerException If any of the provided input reference parameters are null.
     */
    public static AVT cmpKIITNF(String innerTag, Pattern p)
    {
        // FAIL-FAST: It is helpful for the user to test the data before building the Predicate.
        // If these tests fail, the returned predicate would absolutely fail.

        final String            innerTagLC  = ARGCHECK.innerTag(innerTag);
        final Predicate<String> pred        = ARGCHECK.REGEX(p);

        // Java's "Lambda-Expression" Syntax (like an "anonymous method").
        // AVT extends functional-interface Predicate<TagNode>

        return (TagNode tn) ->
        {
            // This eliminates testing any TagNode that simply COULD NOT contain
            // attributes.  (an optimization)
            //
            // KIITNF -> Empty Opening HTML TagNode Elements cannot be eliminated!
            // HOWEVER, Closing TagNodes are never included

            if (tn.isClosing) return false;

            // Retrieve the value of the requested "inner-tag" (HTML Attribute) Key-Value Pair
            // from the input HTML-Element (TagNode)

            String itv = tn.AV(innerTagLC);
                // REG-EX MATCHER, MORE EXPENSIVE

            // If the innerTag's value is null, then the inner-tag was not a key-value pair
            // found inside the TagNode.
            //
            // BECAUSE the user requested to "Keep If Inner-Tag Not Found", we must return 
            //      in that case.
            //      In Java '||' uses short-circuit boolean-evaluation, while '|' requires
            //      full-evaluation.
            //
            // OTHERWISE return the results of running the Regular-Expression matcher using the
            //      input 'Pattern' instance.

            return (itv == null) || pred.test(itv);
        };
    }

    // ********************************************************************************************
    // Predicate<String> factory builders.
    // ********************************************************************************************

    /**
     * Convenience Method.
     * <BR />Invokes: {@link #cmp(String, Predicate)}
     * <BR />Converts: {@link StrFilter} to simple {@code String-Predicate}
     */
    public static AVT cmp(String innerTag, StrFilter innerTagValueTest)
    { return cmp(innerTag, (Predicate<String>) innerTagValueTest::test); }

    /**
     * This is a {@code static} factory method that generates {@code AVT-Predicate's} - 
     * ({@code Predicate<TagNode>}).  It saves the user of typing the lambda information by hand,
     * and does a validation check too.  The primary use of this class is that the results of one
     * factory method may be "AND-chained" or "OR-chained" with another to make search requirements
     * more specific.
     *
     * <BR /><BR /><B>NOTE:</B> The astute observer might wonder why change from a 
     * {@code String-Predicate} to a {@code TagNode-Predicate}, with the answer being that 
     * predicate-chaining on <I>different, multiple inner-tags (and their
     * <B STYLE="color: red;">values</B>)</I> can only be accomplished by using a
     * {@code TagNode-Predicate}, rather than a {@code String-Predicate}
     *
     * @param innerTag This also goes by the term "attribute" in many HTML specifications.  It is
     * the <B STYLE="color: red;">name</B> of the attribute, not it's
     * <B STYLE="color: red;">value</B>. The <B STYLE="color: red;">value</B> will be found (if the
     * {@code TagNode} contains this attribute), and then tested against the
     * {@code String-Predicate} in parameter {@code 'innerTagValueTest'}.
     *
     * @param innerTagValueTest  This may be any Java {@code String-Predicate} with a 
     * {@code test(...) / accept} method.  It will be used to accept or reject the inner-tag's
     * <B STYLE="color: red;">value</B>
     *
     * @return <EMBED CLASS='external-html' DATA-FILE-ID=RETCMP3>
     *
     * @see InnerTagFind
     * @see ARGCHECK#innerTag(String)
     * @see TagNode#AV(String)
     *
     * @throws InnerTagKeyException <EMBED CLASS='external-html' DATA-FILE-ID=ITKEYEX>
     * @throws NullPointerException If any of the provided input reference parameters are null.
     */
    public static AVT cmp(String innerTag, Predicate<String> innerTagValueTest)
    {
        // FAIL-FAST: It is helpful for the user to test the data before building the Predicate.
        // If these tests fail, the returned predicate would absolutely fail.

        final String innerTagLC = ARGCHECK.innerTag(innerTag);
        if (innerTagValueTest == null) throw new NullPointerException
            ("Parameter innerTagValueTest was passed null, but this is not allowed here.");

        // Minimum length for field TagNode.str to have before it could possible contain the attribute
        // Obviously, the TagNode would have to have a min-length that includes the attribute-name
        // length + '< ' and '>'

        final int MIN_LEN = innerTag.length() + 3;

        // Java's "Lambda-Expression" Syntax (like an "anonymous method").
        // AVT extends functional-interface Predicate<TagNode>

        return (TagNode tn) ->
        {
            // This eliminates testing any TagNode that simply COULD NOT contain the
            // attribute.  (an optimization)

            if (tn.isClosing || (tn.str.length() <= (tn.tok.length() + MIN_LEN))) return false;

            // Retrieve the value of the requested "inner-tag" (HTML Attribute) Key-Value Pair
            // from the input HTML-Element (TagNode)

            String itv = tn.AV(innerTagLC);
                // REG-EX MATCHER, MORE EXPENSIVE

            // If the innerTag's value is null, then the inner-tag was not a key-value pair
            // found inside the TagNode: return false.
            // Otherwise return the results of the Predicate<String> provided on that
            // attribute-value.

            return (itv == null) ? false : innerTagValueTest.test(itv);
        };
    }

    /**
     * Convenience Method.
     * <BR />Invokes: {@link #cmpKIITNF(String, Predicate)}
     * <BR />Converts: {@link StrFilter} to {@code String-Predicate}
     */
    public static AVT cmpKIITNF(String innerTag, StrFilter innerTagValueTest)
    { return cmpKIITNF(innerTag, (Predicate<String>) innerTagValueTest::test); }

    /**
     * <EMBED CLASS='external-html' DATA-FILE-ID=CMPKIITNF3>
     *
     * @param innerTag This also goes by the term "attribute" in many HTML specifications.  It is
     * the <B STYLE="color: red;">name</B> of the attribute, not it's
     * <B STYLE="color: red;">value</B>. The <B STYLE="color: red;">value</B> will be found (if the
     * {@code TagNode} contains this attribute), and then tested against the
     * {@code String-Predicate} parameter {@code 'innerTagValueTest'}.
     *
     * @param innerTagValueTest  This may be any Java {@code String-Predicate} with a 
     * {@code test(...) / accept} method.  It will be used to accept or reject the inner-tag's
     * value.
     *
     * @return An instance of {@code 'AVT'} that can be passed to the NodeSearch classes
     * search-methods via any one of the methods that accepts a {@code Predicate<TagNode>} as a
     * parameter in the search criteria.
     *
     * @see #cmp(String, Predicate)
     *
     * @throws InnerTagKeyException <EMBED CLASS='external-html' DATA-FILE-ID=ITKEYEX>
     * @throws NullPointerException If any of the provided input reference parameters are null.
     */
    public static AVT cmpKIITNF(String innerTag, Predicate<String> innerTagValueTest)
    {
        // FAIL-FAST: It is helpful for the user to test the data before building the Predicate.
        // If these tests fail, the returned predicate would absolutely fail.

        final String innerTagLC = ARGCHECK.innerTag(innerTag);

        if (innerTagValueTest == null) throw new NullPointerException
            ("Parameter innerTagValueTest was passed null, but this is not allowed here.");

        // Java's "Lambda-Expression" Syntax (like an "anonymous method").
        // AVT extends functional-interface Predicate<TagNode>

        return (TagNode tn) ->
        {
            // This eliminates testing any TagNode that simply COULD NOT contain
            // attributes.  (an optimization)
            //
            // KIITNF -> Empty Opening HTML TagNode Elements cannot be eliminated!
            // HOWEVER, Closing TagNodes are never included

            if (tn.isClosing) return false;

            // Retrieve the value of the requested "inner-tag" (HTML Attribute) Key-Value Pair
            // from the input HTML-Element (TagNode)
            //
            // REG-EX MATCHER, MORE EXPENSIVE

            String itv = tn.AV(innerTagLC);

            // If the innerTag's value is null, then the inner-tag was not a key-value pair
            // found inside the TagNode.
            //
            // BECAUSE the user requested to "Keep If Inner-Tag Not Found", we must return TRUE
            //          in that case.
            //          In Java '||' uses short-circuit boolean-evaluation, while '|' requires
            //          full-evaluation.
            //
            // OTHERWISE return the results of the Predicate<String> provided on that
            //           attribute-value.

            return (itv == null) || innerTagValueTest.test(itv);
        };
    }

    // ********************************************************************************************
    // Simple Present-Or-Not-Present test
    // ********************************************************************************************

    /**
     * This is a {@code static} factory method that generates {@code AVT-Predicate's} - 
     * ({@code Predicate<TagNode>}).  It saves the user of typing the lambda information by hand,
     * and does a validation check too.  The primary use of this class is that the results of one
     * factory method may be "AND-chained" or "OR-chained" with another to make search requirements
     * more specific.
     *
     * @param innerTag This also goes by the term "attribute" in many HTML specifications.  It is
     * the <B STYLE="color: red;">name</B> of the attribute, not it's
     * <B STYLE="color: red;">value</B>.  If this attribute is found, this {@code Predicate} will
     * always return {@code TRUE} regardless of it's <B STYLE="color: red;">value</B> - so long as
     * it is not null.
     *
     * <BR /><BR /><B><SPAN STYLE="color:red;">IMPORTANT NOTE:</B></SPAN> There is a subtlety here
     * between inner-tag's that have a <B STYLE="color: red;">value</B> of {@code the-empty-string,
     * a zero-length-string}, and attributes that are "null" or not found at all.  Though rare, it
     * is sometimes the case that an HTML Attribute may have a <B STYLE="color: red;">value</B> of
     * {@code <SOME-TAG SOME-INNER-TAG="">}.  There can be other versions that leave the quotes off
     * entirely such as: {@code <OTHER-ELEMENT OTHER-ATTRIBUTE=>} - where there are no quotes at
     * all. If the attribute is found, <I>with an equals sign</I> it will evaluate to the
     * <B><I>{@code the zero-length-string}</I></B>, but if the attribute is not found at all,
     * searching for it will return null, and this {@code Predicate} will return {@code FALSE}.
     *
     * @return <EMBED CLASS='external-html' DATA-FILE-ID=RETCMP4>
     *
     * @see InnerTagFind
     * @see ARGCHECK#innerTag(String)
     * @see TagNode#AV(String)
     *
     * @throws InnerTagKeyException <EMBED CLASS='external-html' DATA-FILE-ID=ITKEYEX>
     * 
     * @throws NullPointerException If any of the provided input reference parameters are null.
     */
    public static AVT cmp(String innerTag)
    {
        // FAIL-FAST: It is helpful for the user to test the data before building the Predicate.
        // If this test fails, the returned predicate would absolutely fail.

        final String innerTagLC = ARGCHECK.innerTag(innerTag);

        // SIMPLIFIED LAMBDA: The contents of this "anonymous method" can be expressed in a
        // single-statement.  No need for 'return' or 'curly-braces'
        // Returns TRUE if the HTML Element contained a copy of the named inner-tag, and false
        // otherwise.

        return (TagNode tn) -> tn.AV(innerTagLC) != null;
    }

    // ******************************************************************************************
    // The basic-required methods, of a "Functional-Interface Predicate"
    // ******************************************************************************************

    /**
     * Generates a new {@code 'AVT'} predicate test that {@code logically-AND's} the results of
     * {@code 'this' Predicate} with the results of the new, additional passed parameter
     * {@code Predicate 'additionalTest'}. 
     *
     * @param additionalTest This is an additional test of the inner-tag
     * <B STYLE="color: red;">key-value pair</B> (also known as the
     * <B STYLE="color: red;">"attribute-value pair"</B>) of HTML {@code TagNode's}.
     *
     * @return A new {@code Predicate<TagNode>} that will use two tests:
     * {@code 'this'} and {@code 'additionalTest'} and subsequently perform a logical-AND on the
     * result.  Short-circuit evaluation is used (specifically, the {@code '&&'} operator,
     * rather than the {@code '&'} operator are utilized).  The {@code Predicate} that is returned
     * will perform the {@code 'this'} test first, and then the {@code 'additionalTest'} second.  
     * The returned {@code Predicate} will return the {@code 'AND'} of both of them.
     *
     * @see TagNode
     *
     * @throws NullPointerException If any of the provided input reference parameters are null.
     */
    default AVT and(AVT additionalTest)
    {
        // FAIL-FAST: It is helpful for the user to test the data before building the Predicate.
        // If this test fails, the returned predicate would absolutely fail.

        if (additionalTest == null) throw new NullPointerException
            ("The parameter 'additionalTest' passed to method 'AVT.and(additionalTest)' was null");

        // SIMPLIFIED LAMBDA: The contents of this "anonymous method" can be expressed in a
        // single-statement.  No need for 'return' or 'curly-braces'
        // Returns TRUE if both 'this' evaluates to true on an input HTML Element,
        // and 'other' also evaluates to true for the same element.

        return (TagNode tn) -> this.test(tn) && additionalTest.test(tn);
    }

    /**
     * Generates a new {@code 'AVT'} predicate test that {@code logically-OR's} the results of
     * {@code 'this' Predicate} with the results of the new, additional passed parameter
     * {@code Predicate 'additionalTest'}. 
     *
     * @param additionalTest This is an additional test of the inner-tag
     * <B STYLE="color: red;">key-value pair</B> (also known as the
     * <B STYLE="color: red;">"attribute-value pair"</B>) of HTML {@code TagNode's}.
     *
     * @return A new {@code Predicate<TagNode>} that will use two tests:
     * {@code 'this'} and {@code 'additionalTest'} and subsequently perform a logical-OR on the
     * result.  Short-circuit evaluation is used (specifically, the {@code '||'} operator,
     * rather than the {@code '|'} operator are utilized).  The {@code Predicate} that is returned
     * will perform the {@code 'this'} test first, and then the {@code 'additionalTest'} second.  
     * The returned {@code Predicate} will return the {@code 'OR'} of both of them.
     *
     * @see TagNode
     *
     * @throws NullPointerException If any of the provided input reference parameters are null.
     */
    default AVT or(AVT additionalTest)
    {
        // FAIL-FAST: It is helpful for the user to test the data before building the Predicate.
        // If this test fails, the returned predicate would absolutely fail.

        if (additionalTest == null) throw new NullPointerException
            ("The parameter 'additionalTest' passed to method 'AVT.or(additionalTest)' was null");

        // SIMPLIFIED LAMBDA: The contents of this "anonymous method" can be expressed in a
        // single-statement.  No need for 'return' or 'curly-braces'
        // Returns TRUE if either 'this' evaluates to true on an input HTML Element,
        // and 'other' also evaluates to true for the same element.

        return (TagNode tn) -> this.test(tn) || additionalTest.test(tn);
    }

    /**
     * Generates a new {@code 'AVT'} predicate test that is the {@code logical-NOT} of
     * {@code 'this' Predicate}.
     *
     * @return A new {@code Predicate<TagNode>} that will simply just calls {@code 'this'
     * Predicate}, and puts an exclamation point ({@code logical 'NOT'}) in front of the result.
     *
     * @see TagNode
     */
    default AVT negate()
    {
        // SIMPLIFIED LAMBDA: The contents of this "anonymous method" can be expressed in a
        // single-statement.  No need for 'return' or 'curly-braces'
        // Returns the opposite of whatever result 'this' evaluates using the input HTML Element.

        return (TagNode tn) -> ! this.test(tn);
    }

    /**
     * This is a {@code static} factory method that generates {@code AVT-Predicate's} 
     * ({@code Predicate<TagNode>}).  It saves the user of typing the lambda information by hand,
     * and does a validation check too. 
     *
     * <BR /><BR />If the {@code expectedTN.equals(tn)} fails - specifically using the
     * java-built-in equality-test method {@code 'equals(...)'}, then the generated / returned
     * {@code Predicate} would return {@code TRUE}, and the {@code TagNode} in question would be
     * included in the results.
     *
     * @param expectedTN This is compared against {@code TagNode's} found in the
     * page-{@code Vector} for equality.
     *
     * @return A {@code Predicate<TagNode>} that compares for equality with parameter
     * {@code 'expectedTN'}
     *
     * @see TagNode
     *
     * @throws NullPointerException If any of the provided input reference parameters are null.
     */
    public static AVT isEqualKEEP(TagNode expectedTN)
    {
        // FAIL-FAST: It is helpful for the user to test the data before building the Predicate.
        // If this test fails, the returned predicate would absolutely fail.

        if (expectedTN == null) throw new NullPointerException
            ("The parameter 'expectedTN' passed to method 'AVT.isEqualKEEP(expectedTN)' was null");

        // SIMPLIFIED LAMBDA: The contents of this "anonymous method" can be expressed in a
        // single-statement.  No need for 'return' or 'curly-braces'
        // Returns true if the HTML Element passed to this (anonymous) method is the same as the
        // one passed to 'isEqualsKEEP'
        // Identical to:  (TagNode tn) -> tn.str.equals(expectedTN.str);

        return (TagNode tn) -> tn.equals(expectedTN);
    }

    /**
     * This is a {@code static} factory method that generates {@code AVT-Predicate's}
     * ({@code Predicate<TagNode>}).  It saves the user of typing the lambda information by hand,
     * and does a validation check too. 
     *
     * <BR /><BR />If the {@code expectedTN.equals(tn)} fails - specifically using the
     * java-built-in equality-test method {@code equals(...)} - then the generated / returned
     * {@code Predicate} would return {@code FALSE}, and the {@code TagNode} in question would be
     * filtered from the results.
     *
     * @param expectedTN This is compared against {@code TagNode's} found in the
     * page-{@code Vector} for equality.
     *
     * @return A {@code Predicate<TagNode>} that compares for equality with parameter
     * {@code 'expectedTN'}
     *
     * @see TagNode
     *
     * @throws NullPointerException If any of the provided input reference parameters are null.
     */
    public static AVT isEqualREJECT(TagNode expectedTN)
    {
        // FAIL-FAST: It is helpful for the user to test the data before building the Predicate.
        // If this test fails, the returned predicate would absolutely fail.

        if (expectedTN == null) throw new NullPointerException(
            "The parameter 'expectedTN' passed to method 'AVT.isEqualREJECT(expectedTN)' "+
            "was null"
        );

        // SIMPLIFIED LAMBDA: The contents of this "anonymous method" can be expressed in a
        // single-statement.  No need for 'return' or 'curly-braces'
        // Returns TRUE if the HTML Element passed to this (anonymous) method is the same as the
        // one passed to 'isEqualsKEEP'
        // Identical to:  (TagNode tn) -> ! tn.str.equals(expectedTN.str);

        return (TagNode tn) -> ! tn.equals(expectedTN);
    }
}