package Torello.HTML;

import Torello.Java.*;
import java.util.*;

/**
 * <CODE>AUM (Attribute Update Mode) - Documentation.</CODE><BR /><BR />
 * <EMBED CLASS='external-html' DATA-FILE-ID=AUM>
 *
 * @see Attributes#update(Vector, AUM, String, String, SD)
 * @see Attributes#update(Vector, AUM, int, int, String, String, SD)
 * @see Attributes#update(Vector, AUM, int[], String, String, SD)
 */
public enum AUM
{
    /**
     * {@code Set}, when used as an Attribute Update Method, tells the HTML Element Attribute
     * Update Logic to either <B>1)</B> replace the current
     * attribute-<B STYLE="color: red;">value</B> with the new text-{@code String}, or <B>2)</B> If
     * there is no attribute <B STYLE="color: red;">key-value</B> with the provided inner-tag
     * <B STYLE="color: red;">name</B>, then to create a new attribute for the HTML Element for the
     * provided attribute-<B STYLE="color: red;">key</B> and <B STYLE="color: red;">value</B> and
     * insert this attribute <B STYLE="color: red;">key-value</B> pair into the element.
     *
     * <BR /><BR />Here is how the HTML Element Attribute Update is Performed:
     * 
     * <DIV CLASS="SNIP">{@code
     * // String cur = tn.AV(innerTag);   int i;
     * case Set:  return tn.setAV(innerTag, innerTagValue, quote);
     * }</DIV>
     *
     * <DIV CLASS="EXAMPLE-SCROLL">{@code
     * // Example 1
     * String   innerTag        = "target";
     * String   innerTagValue   = "_BLANK";
     * AUM      mode            = AUM.Set;
     * TagNode  tn              = new TagNode("<A HREF='nextIndex.html'>");
     * TagNode  newTN           = mode.update(tn, innerTag, innerTagValue, SD.SingleQuote);
     * // newTN.str             ==> <A HREF='nextIndex.html' target='_BLANK'>
     *                          // New 'target' attribute key-value pair inserted into HTML Element
     *
     * // Example 2
     * String   innerTag        = "target";
     * String   innerTagValue   = "_BLANK";
     * AUM      mode            = AUM.Set;
     * TagNode  tn              = new TagNode("<A HREF='nextIndex.html' TARGET='_Self'>");
     * TagNode  newTN           = mode.update(tn, innerTag, innerTagValue, SD.SingleQuote);
     * // newTN.str             ==> <A HREF='nextIndex.html' target='_BLANK'>
     *                          // Old 'target' attribute key-value pair is replaced with new value
     * }</DIV>
     * 
     * @see #update(TagNode, String, String, SD)
     * @see HTMLNode#str
     */
    Set,

    /**
     * {@code Replace} when used as an Attribute Update Method, tells the HTML Element Attribute
     * Update Logic to <I><B>replace</I></B> any attribute <B STYLE="color: red;">key-value</B>
     * pair that the Element contains; <B><I>however</I></B> if there is no current 
     * <B STYLE="color: red;">key-value</B> pair that has the provided attribute
     * <B STYLE="color: red;">name</B>, then the HTML Element Node should be skipped, and left
     * un-modified.
     *
     * <BR /><BR />Here is how the HTML Element Attribute Update is Performed:
     * 
     * <DIV CLASS="SNIP">{@code
     * // String cur = tn.AV(innerTag);   int i;
     * case Replace:  if (cur != null) return tn.setAV(innerTag, innerTagValue, quote);
     *                return null;
     * }</DIV>
     *
     * <DIV CLASS="EXAMPLE-SCROLL">{@code
     * // Example 1
     * String   innerTag        = "style";
     * String   innerTagValue   = "color: red;";
     * AUM      mode            = AUM.Replace;
     * TagNode  tn              = new TagNode("<A HREF='nextIndex.html' STYLE='font-weight: bold;'>");
     * TagNode  newTN           = mode.update(tn, innerTag, innerTagValue, SD.SingleQuote);
     * // newTN.str             ==> <A HREF='nextIndex.html' style='color: red;'>
     *                          // Old 'style' attribute key-value pair is replaced with new value  
     *
     * // Example 2
     * String   innerTag        = "style";
     * String   innerTagValue   = "color: red;";
     * AUM      mode            = AUM.Replace;
     * TagNode  tn              = new TagNode("<A HREF='nextIndex.html'>");
     * TagNode  newTN           = mode.update(tn, innerTag, innerTagValue, SD.SingleQuote);
     * // newTN                 ==> null
     *                          // NOTE: HTML Element left unchanged, because it did not actually
     *                          //       have a 'style' attribute in the first place. 
     *                          //       A return value of 'null' implies this AUM does not result
     *                          //       in a replacement or update for the TagNode passed.
     * }</DIV>
     * 
     * @see #update(TagNode, String, String, SD)
     * @see HTMLNode#str
     */ 
    Replace,
 
    /**
     * {@code RemoveSubString} when used as an Attribute Update Method, tells the HTML Element
     * Attribute Update Logic to <I><B>remove</I></B> the first copy found of a provided sub-string
     * from the attribute-<B STYLE="color: red;">value</B> whose attribute
     * <B STYLE="color: red;">name</B> matches the provided inner-tag
     * <B STYLE="color: red;">name</B>.
     *
     * <BR /><BR /><DIV CLASS="MISC_HILITE">
     * <B>For Instance:</B> If AUM.RemoveSubString were used with an HTML Element
     * that looked like: <SPAN STYLE="color: lightbrown; font-weight: bold;">
     * <BR />{@code <DIV CLASS='MyClass MyPage Corporation123'>}</SPAN>
     * 
     * <BR /><BR />
     * <B>Where:</B> {@code innerTag = "CLASS"} and {@code innerTagValue = "Corporation123"}
     * 
     * <BR /><BR /><B>Then:</B> The HTML Element would be updated to:
     * <SPAN STYLE="color: blue; font-weight: bold;">
     * <BR />{@code <DIV CLASS='MyClass MyPage '>}
     * </SPAN>
     * 
     * <BR /><BR /><B>NOTE:</B> This uses Java's {@code String.indexOf(...)} method, and will only
     * remove the first-instance of the substring.
     * 
     * <BR /><BR /><B>ALSO:</B> There is a remaining 'extra-space' that was not removed along with
     * the {@code 'corporation123'} String.  Keep in mind white-space when using java to modify text.
     * </DIV>
     *
     * <BR /><BR />Here is how the HTML Element Attribute Update is Performed:
     * 
     * <DIV CLASS="SNIP">{@code
     * // String cur = tn.AV(innerTag);   int i;
     * case RemoveSubString:  if (cur != null) if ((i = cur.indexOf(innerTagValue)) != -1)
     *                            return tn.setAV(innerTag, cur.replace(innerTagValue, ""), quote);
     *                        return null;
     * }</DIV>
     * 
     * @see #update(TagNode, String, String, SD)
     * @see HTMLNode#str
     */
    RemoveSubString,

    /**
     * This performs the exact same routine as {@code AUM.RemoveSubstring}, however the
     * text-{@code String} comparison ignores case for the alphabetic letters a..z.  This HTML
     * Element Update Routine, just like the {@code AUM.RemoveSubstring}, also only removes the
     * first instance found of the provided substring.
     *
     * <BR /><BR /><DIV CLASS="MISC_HILITE">
     * <B>For Instance:</B> If AUM.RemoveSubString_CI were used with an HTML Element
     * that looked like: <SPAN STYLE="color: lightbrown; font-weight: bold;">
     * <BR />{@code <DIV CLASS='MyClass MyPage Corporation123' STYLE='FONT-WEIGHT: BOLD; COLOR:
     * RED;'>}</SPAN>
     * 
     * <BR /><BR />
     * <B>Where:</B> {@code innerTag = "STYLE"} and {@code innerTagValue = "color: red;"}
     * 
     * <BR /><BR /><B>Then:</B> The HTML Element would be updated to:
     * <SPAN STYLE="color: blue; font-weight: bold;">
     * <BR />{@code <DIV CLASS='MyClass MyPage Corporation123'STYLE='FONT-WEIGHT: BOLD; '>}</SPAN>
     * 
     * <BR /><BR /><B>NOTE:</B> This uses java's {@code StrCmpr.indexOfIgnoreCase(...)} method, and
     * will only remove the first-instance of the substring (ignoring case).  In the original HTML
     * Element, the words 'COLOR' and 'RED' were capitalized.  Using this 'Case-Insensitive'
     * removal, the user can catch any version.  This, fortunately, is how CSS 'Style' Attributes
     * work!
     * 
     * <BR /><BR /><B>ALSO:</B> There is a remaining 'extra-space' that was not removed along with
     * the 'corporation123' string.  Keep in mind white-space when using java to modify text.
     * </DIV>
     *
     * <BR /><BR />Here is how the HTML Element Attribute Update is Performed:
     * 
     * <DIV CLASS="SNIP">{@code
     * // String cur = tn.AV(innerTag);   int i;
     * case RemoveSubString_CI:  if (cur != null) if ((i = StrCmpr.indexOfIgnoreCase(cur, innerTagValue)) != -1)
     *                               return tn.setAV(innerTag, cur.substring(0, i) + cur.substring(i + innerTagValue.length()), quote);
     *                           return null;
     * }</DIV>
     * 
     * @see #update(TagNode, String, String, SD)
     * @see HTMLNode#str
     */
    RemoveSubString_CI,

    /**
     * {@code ConcatToStart} when used as an Attribute Update Method, tells the HTML Element
     * Attribute Update Logic to <I><B>concatenate</I></B> the provided
     * attribute-<B STYLE="color: red;">value</B> to <I><B>an already in place</B></I>
     * attribute-<B STYLE="color: red;">value</B> before the beginning of the current
     * attribute-<B STYLE="color: red;">value</B> {@code String}. <B><I>However</I></B> if there is
     * no current <B STYLE="color: red;">key-value</B> pair that has the provided attribute
     * <B STYLE="color: red;">name</B>, then the HTML Element Node should be skipped, and left
     * un-modified.
     *
     * <BR /><BR />Here is how the HTML Element Attribute Update is Performed:
     * 
     * <DIV CLASS="SNIP">{@code
     * // String cur = tn.AV(innerTag);   int i;
     * case ConcatToStart:  if (cur != null) return tn.setAV(innerTag, innerTagValue + cur, quote);
     *                      return null;
     * }</DIV>
     *
     * <BR /><DIV CLASS="EXAMPLE-SCROLL">{@code
     * // Example 1
     * String   innerTag        = "id";
     * String   innerTagValue   = "JAVA-AUM-";
     * AUM      mode            = AUM.ConcatToStart;
     * TagNode  tn              = new TagNode("<IMG SRC='img-123.jpg' ID='MyPage'>");
     * TagNode  newTN           = mode.update(tn, innerTag, innerTagValue, SD.SingleQuote);
     * // newTN.str             ==> <IMG SRC='img-123.jpg' id='JAVA-AUM-MyPage'>
     *
     * // Example 2
     * String   innerTag        = "id";
     * String   innerTagValue   = "JAVA-AUM-";
     * AUM      mode            = AUM.ConcatToStart;
     * TagNode  tn              = new TagNode("<IMG SRC='img-123.jpg'>");
     * TagNode  newTN           = mode.update(tn, innerTag, innerTagValue, SD.SingleQuote);
     * // newTN                 ==> null
     *                          // NOTE: HTML Element left unchanged, because it did not actually
     *                          //       have an 'id' attribute in the first place. 
     *                          //       A return value of 'null' implies this AUM does not result
     *                          //       in a replacement or update for the TagNode passed.
     * }</DIV>
     * 
     * @see #update(TagNode, String, String, SD)
     * @see HTMLNode#str
     */
    ConcatToStart,

    /**
     * {@code ConcatToStart} when used as an Attribute Update Method, tells the HTML Element
     * Attribute Update Logic to <I><B>concatenate</I></B> the provided
     * attribute-<B STYLE="color: red;">value</B> to <I><B>an already in place</B></I>
     * attribute-<B STYLE="color: red;">value</B> before the beginning of the current
     * attribute-<B STYLE="color: red;">value</B> {@code String}. If there is no current
     * <B STYLE="color: red;">key-value</B> pair that has the provided attribute
     * <B STYLE="color: red;">name</B>, a new Inner-Tag <B STYLE="color: red;">key-value</B> pair
     * should be added to the HTML Element Node using the provided
     * <B STYLE="color: red;">key</B>-{@code String} and
     * <B STYLE="color: red;">value</B>-{@code String}.
     *
     * <BR /><BR />Here is how the HTML Element Attribute Update is Performed:
     * 
     * <DIV CLASS="SNIP">{@code
     * // String cur = tn.AV(innerTag);   int i;
     * case ConcatToStartOrSet:  if (cur != null) return tn.setAV(innerTag, innerTagValue + cur, quote);
     *                           return tn.setAV(innerTag, innerTagValue, quote);
     * }</DIV>
     *
     * <DIV CLASS="EXAMPLE-SCROLL">{@code
     * // Example 1
     * String   innerTag        = "alt";
     * String   innerTagValue   = "This is a personal photo.";
     * AUM      mode            = AUM.ConcatToStartOrSet;
     * TagNode  tn              = new TagNode("<IMG SRC='img-123.jpg'>");
     * TagNode  newTN           = mode.update(tn, innerTag, innerTagValue, SD.SingleQuote);
     * // newTN.str             ==> <IMG SRC='img-123.jpg' alt='This is a personal photo.'>  
     *                          // The original TagNode did not have an 'alt' Inner-Tag, but
     *                          // because this AUM has the "OrSet" requirement, when a TagNode
     *                          // that's lacking the requested Inner-Tag, the AUM.update method
     *                          // will not return null, but instead create a new attribute
     *                          // key-value pair, and set the value to the requested parameter.
     *
     * // Example 2
     * String   innerTag        = "alt";
     * String   innerTagValue   = "This is a personal photo.";
     * AUM      mode            = AUM.ConcatToStartOrSet;
     * TagNode  tn              = new TagNode("<IMG SRC='img-123.jpg' ALT='Bob Wilson'>");
     * TagNode  newTN           = mode.update(tn, innerTag, innerTagValue, SD.SingleQuote);
     * // newTN.str             ==> <IMG SRC='img-123.jpg' alt='This is a personal photo.Bob Wilson'> 
     *                          // NOTE: There is no space between the period, and the beginning of the
     *                          //       next sentence in the ALT Inner-Tag above! 
     * }</DIV>
     * 
     * @see #update(TagNode, String, String, SD)
     * @see Torello.HTML.HTMLNode#str
     */
    ConcatToStartOrSet,

    /**
     * This {@code AUM} enumerated type is precisely identical to the one named
     * {@code ConcatToStart} - <I><B>except</B></I> that in the case where the inner-tag
     * <B STYLE="color: red;">value</B> is appended, a space is added immediately after the newly
     * added {@code String}-<B STYLE="color: red;">value</B> token. 
     * 
     * <BR /><BR /><SPAN STYLE="color: red;"><B>NOTE:</B></SPAN> The primary reason for adding
     * this surprisingly subtle and minor difference is to remind users that keeping up with spaces
     * when tweaking HTML inner-tags can be a bug source.
     *
     * <BR /><BR />Here is how the HTML Element Attribute Update is Performed:
     * 
     * <DIV CLASS="SNIP">{@code
     * // String cur = tn.AV(innerTag);   int i;
     * case ConcatToStartAddSpace:  if (cur != null) return tn.setAV(innerTag, innerTagValue + ' ' + cur, quote);
     *                              return null;
     * }</DIV>
     *
     * <DIV CLASS="EXAMPLE-SCROLL">{@code
     * // Example 1
     * String   innerTag        = "id";
     * String   innerTagValue   = "JAVA-AUM";
     * AUM      mode            = AUM.ConcatToStartAddSpace;
     * TagNode  tn              = new TagNode("<IMG SRC='img-123.jpg' ID='MyPage'>");
     * TagNode  newTN           = mode.update(tn, innerTag, innerTagValue, SD.SingleQuote);
     * // newTN.str             ==> <IMG SRC='img-123.jpg' id='JAVA-AUM MyPage'>
     *
     * // Example 2
     * String   innerTag        = "id";
     * String   innerTagValue   = "JAVA-AUM";
     * AUM      mode            = AUM.ConcatToStartAddSpace;
     * TagNode  tn              = new TagNode("<IMG SRC='img-123.jpg'>");
     * TagNode  newTN           = mode.update(tn, innerTag, innerTagValue, SD.SingleQuote);
     * // newTN                 ==> null
     *                          // NOTE: HTML Element left unchanged, because it did not actually
     *                          //       have an 'id' attribute in the first place. 
     *                          //       A return value of 'null' implies this AUM does not result
     *                          //       in a replacement or update for the TagNode passed.
     * }</DIV>
     * 
     * @see #update(TagNode, String, String, SD)
     * @see Torello.HTML.HTMLNode#str
     */
    ConcatToStartAddSpace,

    /**
     * This {@code AUM} enumerated type is precisely identical to the one named
     * {@code ConcatToStartOrSet} - <I><B>except</B></I> that in the case where the inner-tag
     * <B STYLE="color: red;">value</B> is appended (concatenated), a space is added immediately
     * after the newly added {@code String}-<B STYLE="color: red;">value</B> token.
     *
     * <BR /><BR /><B>NOTE:</B> If there were no inner-tag <B STYLE="color: red;">key-value</B>
     * pair, and a new one was added - then an extra space would, hopefully this is obvious,
     * <I>then an extra space would not be needed</I>, and therefore it is not added.
     *
     * <BR /><BR />Here is how the HTML Element Attribute Update is Performed:
     * 
     * <DIV CLASS="SNIP">{@code
     * // String cur = tn.AV(innerTag);   int i;
     * case ConcatToStartOrSetAddSpace:  if (cur != null) return tn.setAV(innerTag, innerTagValue + ' ' + cur, quote);
     *                                   return tn.setAV(innerTag, innerTagValue, quote);
     * }</DIV>
     *
     * <DIV CLASS="EXAMPLE-SCROLL">{@code
     * // Example 1
     * String   innerTag        = "alt";
     * String   innerTagValue   = "This is a personal photo.";
     * AUM      mode            = AUM.ConcatToStartOrSetAddSpace;
     * TagNode  tn              = new TagNode("<IMG SRC='img-123.jpg' ALT='Company XYZ'>");
     * TagNode  newTN           = mode.update(tn, innerTag, innerTagValue, SD.SingleQuote);
     * // newTN.str             ==> <IMG SRC='img-123.jpg' alt='This is a personal photo. Company XYZ'>  
     *
     * // Example 2
     * String   innerTag        = "alt";
     * String   innerTagValue   = "This is a personal photo.";
     * AUM      mode            = AUM.ConcatToStartOrSetAddSpace;
     * TagNode  tn              = new TagNode("<IMG SRC='img-123.jpg'>");
     * TagNode  newTN           = mode.update(tn, innerTag, innerTagValue, SD.SingleQuote);
     * // newTN.str             ==> <IMG SRC='img-123.jpg' alt='This is a personal photo.'>  
     * }</DIV>
     * 
     * @see #update(TagNode, String, String, SD)
     * @see Torello.HTML.HTMLNode#str
     */
    ConcatToStartOrSetAddSpace,

    /**
     * {@code ConcatToEnd} when used as an Attribute Update Method, tells the HTML Element
     * Attribute Update Logic to <I><B>concatenate</I></B> the provided
     * attribute-<B STYLE="color: red;">value</B> to <I><B>an already in place</B></I>
     * attribute-<B STYLE="color: red;">value</B> at the end of the current
     * attribute-<B STYLE="color: red;">value</B> {@code String}.  <B><I>However</I></B> if there
     * is no current <B STYLE="color: red;">key-value</B> pair that has the provided attribute
     * <B STYLE="color: red;">name</B>, then the HTML Element Node should be skipped, and left
     * un-modified.
     *
     * <BR /><BR />Here is how the HTML Element Attribute Update is Performed:
     * 
     * <DIV CLASS="SNIP">{@code
     * // String cur = tn.AV(innerTag);   int i;
     * case ConcatToEnd:  if (cur != null) return tn.setAV(innerTag, cur + innerTagValue, quote);
     *                    return null;
     * }</DIV>
     *
     * <DIV CLASS="EXAMPLE-SCROLL">{@code
     * // Example 1
     * String   innerTag        = "alt";
     * String   innerTagValue   = "Photo of Friends";
     * AUM      mode            = AUM.ConcatToEnd;
     * TagNode  tn              = new TagNode("<IMG SRC='img-123.jpg' ID='MyPage'>");
     * TagNode  newTN           = mode.update(tn, innerTag, innerTagValue, SD.SingleQuote);
     * // newTN                 ==> null
     *                          // NOTE: HTML Element left unchanged, because it did not actually
     *                          //       have an 'alt' attribute in the first place. 
     *                          //       A return value of 'null' implies this AUM does not result
     *                          //       in a replacement or update for the TagNode passed.
     *
     * // Example 2
     * String   innerTag        = "alt";
     * String   innerTagValue   = " - Photo of Friends";
     * AUM      mode            = AUM.ConcatToEnd;
     * TagNode  tn              = new TagNode("<IMG SRC='img-123.jpg' ALT='Bob Wilson'>");
     * TagNode  newTN           = mode.update(tn, innerTag, innerTagValue, SD.SingleQuote);
     * // newTN.str             ==> <IMG SRC='img-123.jpg' alt='Bob Wilson - Photo of Friends'> 
     * }</DIV>
     * 
     * @see #update(TagNode, String, String, SD)
     * @see Torello.HTML.HTMLNode#str
     */
    ConcatToEnd,

    /**
     * {@code ConcatToEnd} when used as an Attribute Update Method, tells the HTML Element
     * Attribute Update Logic to <I><B>concatenate</I></B> the provided
     * attribute-<B STYLE="color: red;">value</B> to <I><B>an already in place</B></I>
     * attribute-<B STYLE="color: red;">value</B> at the end of the current
     * attribute-<B STYLE="color: red;">value</B> {@code String}.  If there is no current
     * <B STYLE="color: red;">key-value</B> pair that has the provided attribute
     * <B STYLE="color: red;">name</B>, a new Inner-Tag <B STYLE="color: red;">key-value</B> pair
     * should be added to the HTML Element Node using the provided
     * <B STYLE="color: red;">key</B>-{@code String} and
     * <B STYLE="color: red;">value</B>-{@code String}.
     *
     * <BR /><BR />Here is how the HTML Element Attribute Update is Performed:
     * 
     * <DIV CLASS="SNIP">{@code
     * // String cur = tn.AV(innerTag);   int i;
     * case ConcatToEndOrSet:  if (cur != null) return tn.setAV(innerTag, cur + innerTagValue, quote);
     *                         return tn.setAV(innerTag, innerTagValue, quote);
     * }</DIV>
     *
     * <DIV CLASS="EXAMPLE-SCROLL">{@code
     * // Example 1
     * String   innerTag        = "alt";
     * String   innerTagValue   = " - This is a personal photo.";
     * AUM      mode            = AUM.ConcatToEndOrSet;
     * TagNode  tn              = new TagNode("<IMG SRC='img-123.jpg' ALT='Larry'>");
     * TagNode  newTN           = mode.update(tn, innerTag, innerTagValue, SD.SingleQuote);
     * // newTN.str             ==> <IMG SRC='img-123.jpg' alt='Larry - This is a personal photo.'>
     *                          // NOTE: There is no space between the period, and the beginning of
     *                          //       the next sentence in the ALT Inner-Tag above!  
     *
     * // Example 2
     * String   innerTag        = "alt";
     * String   innerTagValue   = "This is a personal photo.";
     * AUM      mode            = AUM.ConcatToEndOrSet;
     * TagNode  tn              = new TagNode("<IMG SRC='img-123.jpg'>");
     * TagNode  newTN           = mode.update(tn, innerTag, innerTagValue, SD.SingleQuote);
     * // newTN.str             ==> <IMG SRC='img-123.jpg' alt='This is a personal photo.'>
     *                          // The original TagNode did not have an 'alt' Inner-Tag, but
     *                          // because this AUM has the "OrSet" requirement, when a TagNode
     *                          // that's lacking the requested Inner-Tag, the AUM.update method
     *                          // will not return null, but instead create a new attribute
     *                          // key-value pair, and set the value to the requested parameter.
     * }</DIV>
     * 
     * @see #update(TagNode, String, String, SD)
     * @see Torello.HTML.HTMLNode#str
     */
    ConcatToEndOrSet,

    /**
     * This {@code AUM} enumerated type is precisely identical to the one named {@code ConcatToEnd}
     * - <I><B>except</B></I> that in the case where the inner-tag <B STYLE="color: red;">value</B>
     * is appended, a space is added immediately before the newly added
     * {@code String}-<B STYLE="color: red;">value</B> token.
     * 
     * <BR /><BR /><SPAN STYLE="color: red;">NOTE:</SPAN> The primary reason for adding this
     * surprisingly subtle and minor difference is to remind users that keeping up with spaces when
     * tweaking HTML inner-tags can be a bug source.
     *
     * <BR /><BR />Here is how the HTML Element Attribute Update is Performed:
     * 
     * <DIV CLASS="SNIP">{@code
     * // String cur = tn.AV(innerTag);   int i;
     * case ConcatToEndAddSpace:
     *      if (cur != null) return tn.setAV(innerTag, cur + ' ' + innerTagValue, quote);
     *      return null;
     * }</DIV>
     *
     * <DIV CLASS="EXAMPLE-SCROLL">{@code
     * // Example 1
     * String   innerTag        = "id";
     * String   innerTagValue   = "JAVA-AUM-EXAMPLE";
     * AUM      mode            = AUM.ConcatToEndAddSpace;
     * TagNode  tn              = new TagNode("<IMG SRC='img-123.jpg'>");
     * TagNode  newTN           = mode.update(tn, innerTag, innerTagValue, SD.SingleQuote);
     * // newTN                 ==> null
     *                          // NOTE: HTML Element left unchanged, because it did not actually
     *                          //       have an 'id' attribute in the first place. 
     *                          //       A return value of 'null' implies this AUM does not result
     *                          //       in a replacement or update for the TagNode passed.
     *
     * // Example 2
     * String   innerTag        = "id";
     * String   innerTagValue   = "JAVA-AUM-EXAMPLE";
     * AUM      mode            = AUM.ConcatToEndAddSpace;
     * TagNode  tn              = new TagNode("<IMG SRC='img-123.jpg' ID='MyClass'>");
     * TagNode  newTN           = mode.update(tn, innerTag, innerTagValue, SD.SingleQuote);
     * // newTN.str             ==> <IMG SRC='img-123.jpg' id='MyClass JAVA-AUM-EXAMPLE'>
     * }</DIV>
     * 
     * @see #update(TagNode, String, String, SD)
     * @see Torello.HTML.HTMLNode#str
     */
    ConcatToEndAddSpace,

    /**
     * This {@code AUM} enumerated type is precisely identical to the one named {@code ConcatToEnd}
     * - <I><B>except</B></I> that in the case where the inner-tag <B STYLE="color: red;">value</B>
     * is appended, a space is added immediately before the newly added
     * {@code String}-<B STYLE="color: red;">value</B> token.
     *
     * <BR /><BR /><B>NOTE:</B> If there were no inner-tag <B STYLE="color: red;">key-value</B>
     * pair, and a new one was added - then an extra space would, hopefully this is obvious,
     * <I>then an extra space would not be needed</I>, and therefore it is not added.
     *
     * <BR /><BR />Here is how the HTML Element Attribute Update is Performed:
     * 
     * <DIV CLASS="SNIP">{@code
     * // String cur = tn.AV(innerTag);   int i;
     * case ConcatToEndOrSetAddSpace:
     *      if (cur != null) return tn.setAV(innerTag, cur + ' ' + innerTagValue, quote);
     *          return tn.setAV(innerTag, innerTagValue, quote);
     * }</DIV>
     *
     * <DIV CLASS="EXAMPLE-SCROLL">{@code
     * // Example 1
     * String   innerTag        = "alt";
     * String   innerTagValue   = "This is a corporate photo.";
     * AUM      mode            = AUM.ConcatToEndOrSetAddSpace;
     * TagNode  tn              = new TagNode("<IMG SRC='img-123.jpg'>");
     * TagNode  newTN           = mode.update(tn, innerTag, innerTagValue, SD.SingleQuote);
     * // newTN.str             ==> <IMG SRC='img-123.jpg' alt='This is a corporate photo.'> 
     *
     * // Example 2
     * String   innerTag        = "alt";
     * String   innerTagValue   = "This is a corporate photo.";
     * AUM      mode            = AUM.ConcatToEndOrSetAddSpace;
     * TagNode  tn              = new TagNode("<IMG SRC='img-123.jpg' ALT='Bob'>");
     * TagNode  newTN           = mode.update(tn, innerTag, innerTagValue, SD.SingleQuote);
     * // newTN.str             ==> <IMG SRC='img-123.jpg' alt='Bob - This is a corporate photo.'
     * }</DIV>
     * 
     * @see #update(TagNode, String, String, SD)
     * @see Torello.HTML.HTMLNode#str
     */
    ConcatToEndOrSetAddSpace;

    /**
     * This performs the Update corresponding to the Attribute-Update-Mode for the particular
     * AUM instance for {@code 'this'} enumerated-type object reference.
     * 
     * @param tn This HTML Element TagNode on which the update shall be performed.
     * @param innerTag The Inner-Tag Key Name to look for inside the HTML Element. 
     * @param innerTagValue The Inner-Tag Value to update, remove, concatenate, append or set.
     * 
     * @param quote This is a major issue in HTML / Java Programming.  The best thing to do is
     * to not try to solve this problem at the lower-level, but rather propagate it up.
     * 
     * @return a newly updated or modified TagNode reference object.  If the update mode did not
     * permit an attribute removal, update, or addition, then 'null' shall be returned.  Again,
     * if 'null' is returned, it means the TagNode did not change - or, rather - <I>did not need
     * to be changed as per the requirements of the chosen Attribute Update Method (AUM).</I>
     */
    public final TagNode update(TagNode tn, String innerTag, String innerTagValue, SD quote)
    {
        String cur = tn.AV(innerTag);
        int i;

        switch (this)
        {
            case Set:
                return tn.setAV(innerTag, innerTagValue, quote);

            case Replace:
                if (cur != null) return tn.setAV(innerTag, innerTagValue, quote);
                return null;

            case RemoveSubString:

                if ((cur != null) && ((i = cur.indexOf(innerTagValue)) != -1))
                    return tn.setAV(innerTag, cur.replace(innerTagValue, ""), quote);

                return null;

            case RemoveSubString_CI:

                if ((cur != null) && ((i = StrIndexOf.first_CI(cur, innerTagValue)) != -1))
                    return tn.setAV(innerTag, cur.substring(0, i) +
                        cur.substring(i + innerTagValue.length()), quote);

                return null;

            case ConcatToStart:
                if (cur != null) return tn.setAV(innerTag, innerTagValue + cur, quote);
                return null;

            case ConcatToStartOrSet:
                if (cur != null) return tn.setAV(innerTag, innerTagValue + cur, quote);
                return tn.setAV(innerTag, innerTagValue, quote);

            case ConcatToStartAddSpace:
                if (cur != null) return tn.setAV(innerTag, innerTagValue + ' ' + cur, quote);
                return null;

            case ConcatToStartOrSetAddSpace:
                if (cur != null) return tn.setAV(innerTag, innerTagValue + ' ' + cur, quote);
                return tn.setAV(innerTag, innerTagValue, quote);

            case ConcatToEnd:
                if (cur != null) return tn.setAV(innerTag, cur + innerTagValue, quote);
                return null;

            case ConcatToEndOrSet:
                if (cur != null) return tn.setAV(innerTag, cur + innerTagValue, quote);
                return tn.setAV(innerTag, innerTagValue, quote);

            case ConcatToEndAddSpace:
                if (cur != null) return tn.setAV(innerTag, cur + ' ' + innerTagValue, quote);
                return null;

            case ConcatToEndOrSetAddSpace:
                if (cur != null) return tn.setAV(innerTag, cur + ' ' + innerTagValue, quote);
                return tn.setAV(innerTag, innerTagValue, quote);

            default: throw new UnreachableError();
        }
    }
}