An attribute within a tag.
Holds the name, assignment string, value and quote character.
This class was made deliberately simple. Except for
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).
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
label="A multi word value."
you could use:
attribute = new Attribute ();
attribute.setName ("label");
attribute.setAssignment ("=");
attribute.setValue ("A multi word value.");
attribute.setQuote ('"');
or
attribute = new Attribute ();
attribute.setName ("label");
attribute.setAssignment ("=");
attribute.setRawValue ("A multi word value.");
or
attribute = new Attribute ("label", "A multi word value.");
Note that the assignment value and quoting need to be set separately when
building the attribute from scratch using the properties.
Valid States for Attributes.Description | toString() | Name | Assignment | Value | Quote |
---|
whitespace attribute | value | null | null | "value" | 0 |
standalone attribute | name | "name" | null | null | 0 |
empty attribute | name= | "name" | "=" | null | 0 |
empty single quoted attribute | name='' | "name" | "=" | null | ' |
empty double quoted attribute | name="" | "name" | "=" | null | " |
naked attribute | name=value | "name" | "=" | "value" | 0 |
single quoted attribute | name='value' | "name" | "=" | "value" | ' |
double quoted attribute | name="value" | "name" | "=" | "value" | " |
In words:
If Name is null, and Assignment is null, and Quote is zero,
it's whitepace and Value has the whitespace text -- value
If Name is not null, and both Assignment and Value are null
it's a standalone attribute -- name
If Name is not null, and Assignment is an equals sign, and Quote is zero
it's an empty attribute -- name=
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=''
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=""
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
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'
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"
All other states are invalid HTML.
From the
HTML 4.01 Specification, W3C Recommendation 24 December 1999
http://www.w3.org/TR/html4/intro/sgmltut.html#h-3.2.2:
3.2.2 Attributes
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.
In this example, the id attribute is set for an H1 element:
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 (") and single quotes (').
For doublequotes authors can also use the character entity reference
".
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.
Attribute names are always case-insensitive.
Attribute values are generally case-insensitive. The definition of each
attribute in the reference manual indicates whether its value is
case-insensitive.
All the attributes defined by this specification are listed in the
attribute
index.
getAssignment
public String getAssignment()
Get the assignment string of this attribute.
This is usually just an equals sign, but in poorly formed attributes it
can include whitespace on either or both sides of an equals sign.
getAssignment
public void getAssignment(StringBuffer buffer)
Get the assignment string of this attribute.
buffer
- The buffer to place the assignment string in.
getLength
public int getLength()
Get the length of the string value of this attribute.
- The number of characters required to express this attribute.
getName
public String getName()
Get the name of this attribute.
The part before the equals sign, or the contents of the
stand-alone attribute.
- The name, or
null
if it's just a whitepace
'attribute'.
getName
public void getName(StringBuffer buffer)
Get the name of this attribute.
buffer
- The buffer to place the name in.
getQuote
public char getQuote()
Get the quote, if any, surrounding the value of the attribute, if any.
- Either ' or " if the attribute value was quoted, or zero
if there are no quotes around it.
getQuote
public void getQuote(StringBuffer buffer)
Get the quote, if any, surrounding the value of the attribute, if any.
buffer
- The buffer to place the quote in.
getRawValue
public String getRawValue()
Get the raw value of the attribute.
The part after the equals sign, or the text if it's just a whitepace
'attribute'. This includes the quotes around the value if any.
- The value, or
null
if it's a stand-alone attribute,
or the text if it's just a whitepace 'attribute'.
getRawValue
public void getRawValue(StringBuffer buffer)
Get the raw value of the attribute.
The part after the equals sign, or the text if it's just a whitepace
'attribute'. This includes the quotes around the value if any.
buffer
- The string buffer to append the attribute value to.
getValue
public String getValue()
Get the value of the attribute.
The part after the equals sign, or the text if it's just a whitepace
'attribute'.
NOTE: This does not include any quotes that may have enclosed
the value when it was read. To get the un-stripped value use
getRawValue
.
- The value, or
null
if it's a stand-alone or
empty attribute, or the text if it's just a whitepace 'attribute'.
getValue
public void getValue(StringBuffer buffer)
Get the value of the attribute.
buffer
- The buffer to place the value in.
isEmpty
public boolean isEmpty()
Predicate to determine if this attribute has an equals sign but no value.
true
if this attribute is an empty attribute.
false
if has an equals sign and a value.
isStandAlone
public boolean isStandAlone()
Predicate to determine if this attribute has no equals sign (or value).
true
if this attribute is a standalone attribute.
false
if has an equals sign.
isValued
public boolean isValued()
Predicate to determine if this attribute has a value.
true
if this attribute has a value.
false
if it is empty or standalone.
isWhitespace
public boolean isWhitespace()
Predicate to determine if this attribute is whitespace.
true
if this attribute is whitespace,
false
if it is a real attribute.
setAssignment
public void setAssignment(String assignment)
Set the assignment string of this attribute.
WARNING: Setting this property to other than an equals sign
or
null
will result in malformed HTML. In the case of a
null
, the
value
should also be set to
null
.
assignment
- The new assignment string.
setName
public void setName(String name)
Set the name of this attribute.
Set the part before the equals sign, or the contents of the
stand-alone attribute.
WARNING: Setting this to null
can result in
malformed HTML if the assignment string is not null
.
setQuote
public void setQuote(char quote)
Set the quote surrounding the value of the attribute.
WARNING: Setting this property to zero will result in malformed
HTML if the value
needs to be quoted (i.e. contains
whitespace).
quote
- The new quote value.
setRawValue
public void setRawValue(String value)
Set the value of the attribute and the quote character.
If the value is pure whitespace, assign it 'as is' and reset the
quote character. If not, check for leading and trailing double or
single quotes, and if found use this as the quote character and
the inner contents of value
as the real value.
Otherwise, examine the string to determine if quotes are needed
and an appropriate quote character if so. This may involve changing
double quotes within the string to character references.
setValue
public void setValue(String value)
Set the value of the attribute.
The part after the equals sign, or the text if it's a whitepace
'attribute'.
WARNING: Setting this property to a value that needs to be
quoted without also setting the quote character will result in malformed
HTML.
toString
public String toString()
Get a text representation of this attribute.
Suitable for insertion into a tag, the output is one of
the forms:
value
name
name=
name=value
name='value'
name="value"
- A string that can be used within a tag.
toString
public void toString(StringBuffer buffer)
Get a text representation of this attribute.
buffer
- The accumulator for placing the text into.