package Torello.HTML;

import java.util.regex.*;

import Torello.HTML.parse.HTMLRegEx;

/**
 * This occurs whenever a parameter specifies an Inner-Tag
 * <B STYLE="color: red;">"Key-Value Pair"</B> (which, in this package, are <I>also known
 * as</I> Attribute-<B STYLE="color: red;">Value</B> Pairs) that contain inappropriate characters
 * inside the {@code key-String}.
 *
 * <BR /><BR /><B>Rules State:</B> All matching HTML Element Attributes must have
 * attribute-<B STYLE="color: red;">names</B> (inner-tags) whose nomenclature conforms to this
 * regular-expression: {@code [A..Za..z][\w-]+}  All this says is that
 * attribute-<B STYLE="color: red;">names</B> <I>must begin with an alphabetic character</I>, and 
 * then the characters that follow must be "regular-expression" {@code word-characters '\w'}.  In a
 * regular-expression, the characters that match a {@code \w} include the letters {@code A-Z}, the
 * (lower-case) letters {@code a-z}, the digits {@code 0-9}, and the underscore {@code '_'}.  The
 * minus-sign {@code '-'} may also be used in an attribute-<B STYLE="color: red;">name</B><I> (it 
 * just may not be the first character used in an attribute-<B STYLE="color: red;">name</B>)</I>.
 *
 * <DIV CLASS="EXAMPLE">{@code 
 *  <IMG SRC="http://example.com/pic.jpg">
 *  <DIV data-id="this is example data">
 * }</DIV>
 * <BR />For the above two examples, both the {@code 'SRC'} attribute-name (key-name) and the
 * {@code 'data-id'} key-<B STYLE="color: red;">name</B> are legitimately named.  No exceptions would
 * be thrown if a programmer initiated a search using a string to look for an inner-tag that was named
 * {@code 'src'} nor would there be problems using a string named {@code 'data-id'} to look for the
 * <B STYLE="color: red;">value</B> of {@code data-id} above.
 *
 * <DIV CLASS="EXAMPLE">{@code 
 * Properties p = new java.util.Properties();
 * p.put("My Attribute Value", "data 1");
 * p.put("123Attribute", "data 2");
 * p.put("SpecialChars!@#$%", "data 3");
 * TagNode tn = new TagNode("DIV", p, SD.DoubleQuotes, false);
 * }</DIV>
 * <BR />An {@code InnerTagKeyException} would be generated <I>for all three cases!</I>  Each of the
 * above inner-tag <B STYLE="color: red;">key-value pairs</B> have key-<B STYLE="color: red;">names</B>
 * with illegal characters.
 * 
 * <BR /><BR /><B>Specifically:</B>
 * <BR /><BR /><UL CLASS="JDUL">
 * <LI>Attribute-Value Pair 1: The key-<B STYLE="color: red;">name</B> contains a space.</LI>
 * <LI>Attribute-Value Pair 2: The key-<B STYLE="color: red;">name</B> begins with a number.</LI>
 * <LI>Attribute-Value Pair 3: The key-<B STYLE="color: red;">name</B> has invalid, non-alpha-numeric
 *     characters!</LI>
 * </UL>
 * <BR />If a search were made using an inner-tag (attribute-<B STYLE="color: red;">name</B>) using
 * a {@code String} that did not meet these criteria, an {@code InnerTagKeyException} would be thrown.
 *
 */
public class InnerTagKeyException extends IllegalArgumentException
{
    /** <EMBED CLASS="external-html" DATA-FILE-ID="SVUIDEX"> */
    public static final long serialVersionUID = 1;

    /** Constructs an {@code InnerTagKeyException} with no detail message. */
    public InnerTagKeyException()
    { super(); }

    /**
     * Constructs an {@code InnerTagKeyException} with the specified detail message.
     * @param message the detail message.
     */
    public InnerTagKeyException(String message)
    { super(message); }

    /**
     * Constructs a new exception with the specified detail message and cause.
     * 
     * <BR /><BR /><B>NOTE:</B> The detail message associated with cause is not automatically
     * incorporated in this exception's detail message.
     * 
     * @param message The detail message (which is saved for later retrieval by the
     * {@code Throwable.getMessage()} method).
     * 
     * @param cause the cause (which is saved for later retrieval by the
     * {@code Throwable.getCause()} method).  (A null value is permitted, and indicates that the
     * cause is nonexistent or unknown).
     */
    public InnerTagKeyException(String message, Throwable cause)
    { super(message, cause); }

    /**
     * Constructs a new exception with the specified cause and a detail message of
     * {@code (cause==null ? null : cause.toString())} (which typically contains the class and
     * detail message of cause).
     * 
     * This constructor is useful for exceptions that are little more than wrappers for other
     * throwables.
     * 
     * @param cause The cause (which is saved for later retrieval by the
     * {@code Throwable.getCause()} method).  (A null value is permitted, and indicates that the
     * cause is nonexistent or unknown.)
     */
    public InnerTagKeyException(Throwable cause)
    { super(cause); }

    /**
     * This verifies that any Java-{@code String} that is intended to be use as an inner-tag
     * conforms to the right rules.  If a problem is found, then an {@code InnerTagKeyException} or
     * {@code NullPointerException} is thrown.
     * 
     * @param keys One or many HTML-Inner-Tag to be checked for use as an HTML-Attribute
     * <B STYLE="color: red;">name</B>
     * 
     * @throws InnerTagKeyException If any {@code String} does not match the {@code CHECK_KEY}
     * Regular-Expression {@code Pattern}.
     * 
     * @throws NullPointerException If any of the attributes / inner-tag
     * <B STYLE="color: red;">keys</B> passed are null.
     * 
     * @see TagNode.AttrRegEx#ATTRIBUTE_KEY_REGEX
     */
    public static void check(String... keys)
    {
        for (String key : keys)

            if (key == null) throw new NullPointerException(
                "You have passed a null as an Attribute-Name (also known as an " +
                "'InnerTag-Key Name'), but this is not allowed."
            );

            else if (! TagNode.AttrRegEx.ATTRIBUTE_KEY_REGEX.matcher(key).find())
                throw new InnerTagKeyException
                    ("Inner-tag key has invalid characters: [" + key + ']');
    }

    /**
     * This method is <B>identical</B> to the <B>{@code public static void check(key);}</B>, except
     * it allows the programmer to add the <B STYLE="color: red;">key-value pair</B> to the 
     * Exception's error message.  No change to the code is present, except the exception's error
     * message.
     * 
     * @param key Any HTML-Inner-Tag <B STYLE="color: red;">name</B>to be checked for use as an
     * HTML-Attribute
     * 
     * @param value This is the <B STYLE="color: red;">value</B> taken by this
     * <B STYLE="color: red;">key</B>, it is included for error-logging only, but it is not
     * checked.
     * 
     * @throws InnerTagKeyException If this class does not match the {@code CHECK_KEY} 
     * Regular-Expression {@code Pattern}, than it throws.
     * 
     * @see TagNode.AttrRegEx#ATTRIBUTE_KEY_REGEX
     */
    public static void check(String key, String value)
    {
        if (key == null) throw new NullPointerException(
            "You have passed a null as an Attribute-Name (also known as an 'InnerTag-Key Name'), " +
            "but this is not allowed."
        );

        if (! TagNode.AttrRegEx.ATTRIBUTE_KEY_REGEX.matcher(key).find()) 
            throw new InnerTagKeyException(
                "The specified inner-tag key has invalid characters: [" + key + "]\n" +
                "For Key-Value Pair: [" + key + ", " + value + "]"
            );
    }
}