attribute.java

html 解析处理代码

// HTMLParser Library $Name: v1_6 $ - A java-based parser for HTML
// http://sourceforge.org/projects/htmlparser
// Copyright (C) 2004 Derrick Oswald
//
// Revision Control Information
//
// $Source: /cvsroot/htmlparser/htmlparser/src/org/htmlparser/Attribute.java,v $
// $Author: derrickoswald $
// $Date: 2005/11/15 02:09:10 $
// $Revision: 1.8 $
//
// This library is free software; you can redistribute it and/or
// modify it under the terms of the GNU Lesser General Public
// License as published by the Free Software Foundation; either
// version 2.1 of the License, or (at your option) any later version.
//
// This library is distributed in the hope that it will be useful,
// but WITHOUT ANY WARRANTY; without even the implied warranty of
// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
// Lesser General Public License for more details.
//
// You should have received a copy of the GNU Lesser General Public
// License along with this library; if not, write to the Free Software
// Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
//

package org.htmlparser;

import java.io.Serializable;

/**
 * An attribute within a tag.
 * Holds the name, assignment string, value and quote character.
 * <p>
 * This class was made deliberately simple. Except for
 * {@link #setRawValue RawValue}, the properties are completely orthogonal,
 * that is: each property is independant of the others. This means you have
 * enough rope here to hang yourself, and it's very easy to create
 * malformed HTML. Where it's obvious, warnings and notes have been provided
 * in the setters javadocs, but it is up to you -- the programmer --
 * to ensure that the contents of the four fields will yield valid HTML
 * (if that's what you want).
 * <p>
 * Be especially mindful of quotes and assignment strings. These are handled
 * by the constructors where it's obvious, but in general, you need to set
 * them explicitly when building an attribute. For example to construct
 * the attribute <b><code>label="A multi word value."</code></b> you could use:
 * <pre>
 *     attribute = new Attribute ();
 *     attribute.setName ("label");
 *     attribute.setAssignment ("=");
 *     attribute.setValue ("A multi word value.");
 *     attribute.setQuote ('"');
 * </pre>
 * or
 * <pre>
 *     attribute = new Attribute ();
 *     attribute.setName ("label");
 *     attribute.setAssignment ("=");
 *     attribute.setRawValue ("A multi word value.");
 * </pre>
 * or
 * <pre>
 *     attribute = new Attribute ("label", "A multi word value.");
 * </pre>
 * Note that the assignment value and quoting need to be set separately when
 * building the attribute from scratch using the properties.
 * <p>
 * <table width="100.0%" align="Center" border="1">
 *   <caption>Valid States for Attributes.</caption>
 *   <tr>
 *     <th align="Center">Description</th>
 *     <th align="Center">toString()</th>
 *     <th align="Center">Name</th>
 *     <th align="Center">Assignment</th>
 *     <th align="Center">Value</th>
 *     <th align="Center">Quote</th>
 *   </tr>
 *   <tr>
 *     <td align="Center">whitespace attribute</td>
 *     <td align="Center">value</td>
 *     <td align="Center"><code>null</code></td>
 *     <td align="Center"><code>null</code></td>
 *     <td align="Center">"value"</td>
 *     <td align="Center"><code>0</code></td>
 *   </tr>
 *   <tr>
 *     <td align="Center">standalone attribute</td>
 *     <td align="Center">name</td>
 *     <td align="Center">"name"</td>
 *     <td align="Center"><code>null</code></td>
 *     <td align="Center"><code>null</code></td>
 *     <td align="Center"><code>0</code></td>
 *   </tr>
 *   <tr>
 *     <td align="Center">empty attribute</td>
 *     <td align="Center">name=</td>
 *     <td align="Center">"name"</td>
 *     <td align="Center">"="</td>
 *     <td align="Center"><code>null</code></td>
 *     <td align="Center"><code>0</code></td>
 *   </tr>
 *   <tr>
 *     <td align="Center">empty single quoted attribute</td>
 *     <td align="Center">name=''</td>
 *     <td align="Center">"name"</td>
 *     <td align="Center">"="</td>
 *     <td align="Center"><code>null</code></td>
 *     <td align="Center"><code>'</code></td>
 *   </tr>
 *   <tr>
 *     <td align="Center">empty double quoted attribute</td>
 *     <td align="Center">name=""</td>
 *     <td align="Center">"name"</td>
 *     <td align="Center">"="</td>
 *     <td align="Center"><code>null</code></td>
 *     <td align="Center"><code>"</code></td>
 *   </tr>
 *   <tr>
 *     <td align="Center">naked attribute</td>
 *     <td align="Center">name=value</td>
 *     <td align="Center">"name"</td>
 *     <td align="Center">"="</td>
 *     <td align="Center">"value"</td>
 *     <td align="Center"><code>0</code></td>
 *   </tr>
 *   <tr>
 *     <td align="Center">single quoted attribute</td>
 *     <td align="Center">name='value'</td>
 *     <td align="Center">"name"</td>
 *     <td align="Center">"="</td>
 *     <td align="Center">"value"</td>
 *     <td align="Center"><code>'</code></td>
 *   </tr>
 *   <tr>
 *     <td align="Center">double quoted attribute</td>
 *     <td align="Center">name="value"</td>
 *     <td align="Center">"name"</td>
 *     <td align="Center">"="</td>
 *     <td align="Center">"value"</td>
 *     <td align="Center"><code>"</code></td>
 *   </tr>
 * </table>
 * <br>In words:
 * <br>If Name is null, and Assignment is null, and Quote is zero,
 *   it's whitepace and Value has the whitespace text -- value
 * <br>If Name is not null, and both Assignment and Value are null
 *   it's a standalone attribute -- name
 * <br>If Name is not null, and Assignment is an equals sign, and Quote is zero
 *   it's an empty attribute -- name=
 * <br>If Name is not null, and Assignment is an equals sign,
 *   and Value is "" or null, and Quote is '
 *   it's an empty single quoted attribute -- name=''
 * <br>If Name is not null, and Assignment is an equals sign,
 *   and Value is "" or null, and Quote is "
 *   it's an empty double quoted attribute -- name=""
 * <br>If Name is not null, and Assignment is an equals sign,
 *   and Value is something, and Quote is zero
 *   it's a naked attribute -- name=value
 * <br>If Name is not null, and Assignment is an equals sign,
 *   and Value is something, and Quote is '
 *   it's a single quoted attribute -- name='value'
 * <br>If Name is not null, and Assignment is an equals sign,
 *   and Value is something, and Quote is "
 *   it's a double quoted attribute -- name="value"
 * <br>All other states are invalid HTML.
 * <p>
 * From the <a href="http://www.w3.org/TR/html4/intro/sgmltut.html#h-3.2.2">
 * HTML 4.01 Specification, W3C Recommendation 24 December 1999</a>
 * http://www.w3.org/TR/html4/intro/sgmltut.html#h-3.2.2:<p>
 * <cite>
 * 3.2.2 Attributes<p>
 * Elements may have associated properties, called attributes, which may
 * have values (by default, or set by authors or scripts). Attribute/value
 * pairs appear before the final ">" of an element's start tag. Any number
 * of (legal) attribute value pairs, separated by spaces, may appear in an
 * element's start tag. They may appear in any order.<p>
 * In this example, the id attribute is set for an H1 element:
 * <pre>
 * <code>
 * {@.html
 *  <H1 id="section1">
 *  This is an identified heading thanks to the id attribute
 *  </H1>}
 * </code>
 * </pre>
 * By default, SGML requires that all attribute values be delimited using
 * either double quotation marks (ASCII decimal 34) or single quotation
 * marks (ASCII decimal 39). Single quote marks can be included within the
 * attribute value when the value is delimited by double quote marks, and
 * vice versa. Authors may also use numeric character references to
 * represent double quotes (&amp;#34;) and single quotes (&amp;#39;).
 * For doublequotes authors can also use the character entity reference
 * &amp;quot;.<p>
 * In certain cases, authors may specify the value of an attribute without
 * any quotation marks. The attribute value may only contain letters
 * (a-z and A-Z), digits (0-9), hyphens (ASCII decimal 45),
 * periods (ASCII decimal 46), underscores (ASCII decimal 95),
 * and colons (ASCII decimal 58). We recommend using quotation marks even
 * when it is possible to eliminate them.<p>
 * Attribute names are always case-insensitive.<p>
 * Attribute values are generally case-insensitive. The definition of each
 * attribute in the reference manual indicates whether its value is
 * case-insensitive.<p>
 * All the attributes defined by this specification are listed in the
 * <a href="http://www.w3.org/TR/html4/index/attributes.html">attribute
 * index</a>.<p>
 * </cite>
 * <p>
 */
public class Attribute
    implements
        Serializable
{
    /**
     * The name of this attribute.
     * The part before the equals sign, or the stand-alone attribute.
     * This will be <code>null</code> if the attribute is whitespace.
     */
    protected String mName;

    /**
     * The assignment string of the attribute.
     * The equals sign.
     * This will be <code>null</code> if the attribute is a
     * stand-alone attribute.
     */
    protected String mAssignment;

    /**
     * The value of the attribute.
     * The part after the equals sign.
     * This will be <code>null</code> if the attribute is an empty or
     * stand-alone attribute.
     */
    protected String mValue;

    /**
     * The quote, if any, surrounding the value of the attribute, if any.
     * This will be zero if there are no quotes around the value.
     */
    protected char mQuote;

    /**
     * Create an attribute with the name, assignment, value and quote given.
     * If the quote value is zero, assigns the value using {@link #setRawValue}
     * which sets the quote character to a proper value if necessary.
     * @param name The name of this attribute.
     * @param assignment The assignment string of this attribute.
     * @param value The value of this attribute.
     * @param quote The quote around the value of this attribute.
     */
    public Attribute (String name, String assignment, String value, char quote)
    {
        setName (name);
        setAssignment (assignment);
        if (0 == quote)
            setRawValue (value);
        else
        {
            setValue (value);
            setQuote (quote);
        }
    }

    /**
     * Create an attribute with the name, value and quote given.
     * Uses an equals sign as the assignment string if the value is not
     * <code>null</code>, and calls {@link #setRawValue} to get the
     * correct quoting if <code>quote</code> is zero.
     * @param name The name of this attribute.
     * @param value The value of this attribute.
     * @param quote The quote around the value of this attribute.
     */
    public Attribute (String name, String value, char quote)
    {
        this (name, (null == value ? "" : "="), value, quote);
    }

    /**
     * Create a whitespace attribute with the value given.
     * @param value The value of this attribute.
     * @exception IllegalArgumentException if the value contains other than
     * whitespace. To set a real value use {@link #Attribute(String,String)}.
     */
    public Attribute (String value)
        throws
            IllegalArgumentException
    {
        if (0 != value.trim ().length ())
            throw new IllegalArgumentException ("non whitespace value");
        else
        {
            setName (null);
            setAssignment (null);
            setValue (value);
            setQuote ((char)0);
        }
    }

    /**
     * Create an attribute with the name and value given.
     * Uses an equals sign as the assignment string if the value is not
     * <code>null</code>, and calls {@link #setRawValue} to get the
     * correct quoting.
     * @param name The name of this attribute.
     * @param value The value of this attribute.
     */
    public Attribute (String name, String value)
    {
        this (name, (null == value ? "" : "="), value, (char)0);
    }

    /**
     * Create an attribute with the name, assignment string and value given.
     * Calls {@link #setRawValue} to get the correct quoting.
     * @param name The name of this attribute.
     * @param assignment The assignment string of this attribute.
     * @param value The value of this attribute.
     */
    public Attribute (String name, String assignment, String value)
    {
        this (name, assignment, value, (char)0);
    }

    /**
     * Create an empty attribute.
     * This will provide "" from the {@link #toString} and
     * {@link #toString(StringBuffer)} methods.
     */
    public Attribute ()
    {
        this (null, null, null, (char)0);
    }

    /**
     * Get the name of this attribute.
     * The part before the equals sign, or the contents of the
     * stand-alone attribute.
     * @return The name, or <code>null</code> if it's just a whitepace
     * 'attribute'.
     * @see #setName
     */
    public String getName ()
    {
        return (mName);
    }

    /**
     * Get the name of this attribute.
     * @param buffer The buffer to place the name in.
     * @see #getName()
     * @see #setName
     */
    public void getName (StringBuffer buffer)
    {
        if (null != mName)
            buffer.append (mName);
    }

    /**
     * Set the name of this attribute.
     * Set the part before the equals sign, or the contents of the
     * stand-alone attribute.
     * <em>WARNING:</em> Setting this to <code>null</code> can result in
     * malformed HTML if the assignment string is not <code>null</code>.
     * @param name The new name.
     * @see #getName
     * @see #getName(StringBuffer)
     */
    public void setName (String name)
    {
        mName = name;
    }

    /**
     * Get the assignment string of this attribute.