|
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Objectau.id.jericho.lib.html.Segment
au.id.jericho.lib.html.CharacterReference
Represents either a CharacterEntityReference
or NumericCharacterReference
.
This class, together with its subclasses, contains static methods to perform most required operations without ever having to instantiate an object.
Objects of this class are useful when the positions of character references in a source document are required, or to replace the found character references with customised text.
Objects are created using one of the following methods:
parse(CharSequence characterReferenceText)
Source.findNextCharacterReference(int pos)
Source.findPreviousCharacterReference(int pos)
Segment.findAllCharacterReferences()
Field Summary | |
static boolean |
ApostropheEncoded
Determines whether apostrophes are encoded when calling the encode(CharSequence) method. |
static int |
INVALID_CODE_POINT
Represents an invalid Unicode code point. |
Method Summary | |
static java.lang.String |
decode(java.lang.CharSequence encodedText)
Decodes the specified HTML encoded text into normal text. |
static java.lang.String |
decodeCollapseWhiteSpace(java.lang.CharSequence text)
Decodes the specified text after collapsing its white space. |
static java.lang.String |
encode(java.lang.CharSequence unencodedText)
Encodes the specified text, escaping special characters into character references. |
static java.lang.String |
encodeWithWhiteSpaceFormatting(java.lang.CharSequence unencodedText)
Encodes the specified text, preserving line breaks, tabs and spaces for rendering by converting them to markup. |
char |
getChar()
Returns the character represented by this character reference. |
abstract java.lang.String |
getCharacterReferenceString()
Returns the encoded form of this character reference. |
static java.lang.String |
getCharacterReferenceString(int codePoint)
Returns the encoded form of the specified Unicode code point. |
int |
getCodePoint()
Returns the Unicode code point represented by this character reference. |
static int |
getCodePointFromCharacterReferenceString(java.lang.CharSequence characterReferenceText)
Parses a single encoded character reference text into a Unicode code point. |
java.lang.String |
getDecimalCharacterReferenceString()
Returns the decimal encoded form of this character reference. |
static java.lang.String |
getDecimalCharacterReferenceString(int codePoint)
Returns the decimal encoded form of the specified Unicode code point. |
java.lang.String |
getHexadecimalCharacterReferenceString()
Returns the hexadecimal encoded form of this character reference. |
static java.lang.String |
getHexadecimalCharacterReferenceString(int codePoint)
Returns the hexadecimal encoded form of the specified Unicode code point. |
java.lang.String |
getUnicodeText()
Returns the Unicode code point of this character reference in U+ notation. |
static java.lang.String |
getUnicodeText(int codePoint)
Returns the specified Unicode code point in U+ notation. |
static CharacterReference |
parse(java.lang.CharSequence characterReferenceText)
Parses a single encoded character reference text into a CharacterReference object. |
static java.lang.String |
reencode(java.lang.CharSequence encodedText)
Re-encodes the specified text, equivalent to decoding and then encoding again. |
static boolean |
requiresEncoding(char ch)
Indicates whether the specified character would need to be encoded in HTML text. |
Methods inherited from class au.id.jericho.lib.html.Segment |
charAt, compareTo, encloses, encloses, equals, findAllCharacterReferences, findAllComments, findAllElements, findAllElements, findAllStartTags, findAllStartTags, findAllStartTags, findFormControls, findFormFields, findWords, getBegin, getDebugInfo, getEnd, getSourceText, getSourceTextNoWhitespace, hashCode, ignoreWhenParsing, isComment, isWhiteSpace, length, parseAttributes, subSequence, toString |
Methods inherited from class java.lang.Object |
getClass, notify, notifyAll, wait, wait, wait |
Field Detail |
public static final int INVALID_CODE_POINT
This can be the result of parsing a numeric character reference outside of the valid Unicode range of 0x000000-0x10FFFF, or any other invalid character reference.
public static boolean ApostropheEncoded
encode(CharSequence)
method.
This is a global setting which affects all threads.
Specifying a value of false
means apostrophe
(U+0027) characters will not be encoded.
The only time apostrophes need to be encoded is within an attribute value delimited by
single quotes (apostrophes), so in most cases ignoring apostrophes is perfectly safe and
enhances readability of the source document.
The recommended setting is false
, although the default value is true
so that
the behaviour of the encode(CharSequence)
method is consistent with previous versions.
Method Detail |
public int getCodePoint()
public char getChar()
If this character reference represents a Unicode supplimentary code point, any bits outside of the least significant 16 bits of the code point are truncated, yielding an incorrect result.
public static java.lang.String encode(java.lang.CharSequence unencodedText)
Each character is encoded only if the requiresEncoding(char)
method would return true
for that character,
using its CharacterEntityReference
if available, or a decimal NumericCharacterReference
if their Unicode
code point value is greater than U+007F.
The only exception to this is an apostrophe (U+0027),
which depending on the current setting of the static ApostropheEncoded
property,
is either encoded as the numeric character reference "'
" (default setting), or left unencoded.
This method will never encode an apostrophe into its character entity reference "'
" as this
entity is not defined for use in HTML. See the comments in the CharacterEntityReference
class for more information.
To encode text using only numeric character references, use the
NumericCharacterReference.encode(CharSequence unencodedText)
method instead.
unencodedText
- the text to encode.
decode(CharSequence encodedText)
public static java.lang.String encodeWithWhiteSpaceFormatting(java.lang.CharSequence unencodedText)
This performs the same encoding as the encode(CharSequence)
method, but also performs the following conversions:
<br />
". CR/LF pairs are treated as a single line break.
"
while ensuring the last is always a normal space.
The conversion of multiple consecutive spaces to alternating space/non-breaking-space allows the correct number of spaces to be rendered, but also allows the line to wrap in the middle of it.
Note that zero-width spaces (U+200B) are converted to the numeric character reference
​
through the normal encoding process, but IE6 does not render them properly
either encoded or unencoded.
There is no method provided to reverse this encoding.
unencodedText
- the text to encode.
encode(CharSequence unencodedText)
public static java.lang.String decode(java.lang.CharSequence encodedText)
All character entity references and numeric character references are converted to their respective characters.
The SGML specification allows character references without a terminating semicolon (;
) in some circumstances.
Although not permitted in HTML or XHTML, some browsers do accept them.
The behaviour of this library is as follows:
Although character entity references are case sensitive, and in some cases differ from other entity references only by their case, some browsers will also recognise them in a case-insensitive way. For this reason, all decoding methods in this library will recognise character entity references even if they are in the wrong case.
encodedText
- the text to decode.
encode(CharSequence unencodedText)
public static java.lang.String decodeCollapseWhiteSpace(java.lang.CharSequence text)
All leading and trailing white space is omitted, and any sections of internal white space are replaced by a single space.
The resultant text is what would normally be rendered by a user agent.
text
- the source text
FormControl.getPredefinedValues()
public static java.lang.String reencode(java.lang.CharSequence encodedText)
This process ensures that the specified encoded text does not contain any remaining unencoded characters.
IMPLEMENTATION NOTE: At present this method simply calls the decode
method
followed by the encode
method, but a more efficient implementation
may be used in future.
encodedText
- the text to re-encode.
public abstract java.lang.String getCharacterReferenceString()
The exact behaviour of this method depends on the class of this object.
See the CharacterEntityReference.getCharacterReferenceString()
and
NumericCharacterReference.getCharacterReferenceString()
methods for more details.
CharacterReference.parse(">").getCharacterReferenceString()
returns ">
"CharacterReference.parse(">").getCharacterReferenceString()
returns "e;
"
getCharacterReferenceString(int codePoint)
,
getDecimalCharacterReferenceString()
public static java.lang.String getCharacterReferenceString(int codePoint)
This method returns the character entity reference encoded form of the code point if one exists, otherwise it returns the decimal numeric character reference encoded form.
The only exception to this is an apostrophe (U+0027),
which is encoded as the numeric character reference "'
" instead of its character entity reference
"'
".
CharacterReference.getCharacterReferenceString(62)
returns ">
"CharacterReference.getCharacterReferenceString('>')
returns ">
"CharacterReference.getCharacterReferenceString('☺')
returns "☺
"
codePoint
- the Unicode code point to encode.
getHexadecimalCharacterReferenceString(int codePoint)
public java.lang.String getDecimalCharacterReferenceString()
This is equivalent to getDecimalCharacterReferenceString(getCodePoint())
.
CharacterReference.parse(">").getDecimalCharacterReferenceString()
returns ">
"
getCharacterReferenceString()
,
getHexadecimalCharacterReferenceString()
public static java.lang.String getDecimalCharacterReferenceString(int codePoint)
CharacterReference.getDecimalCharacterReferenceString('>')
returns ">
"
codePoint
- the Unicode code point to encode.
getCharacterReferenceString(int codePoint)
,
getHexadecimalCharacterReferenceString(int codePoint)
public java.lang.String getHexadecimalCharacterReferenceString()
This is equivalent to getHexadecimalCharacterReferenceString(getCodePoint())
.
CharacterReference.parse(">").getHexadecimalCharacterReferenceString()
returns ">
"
getCharacterReferenceString()
,
getDecimalCharacterReferenceString()
public static java.lang.String getHexadecimalCharacterReferenceString(int codePoint)
CharacterReference.getHexadecimalCharacterReferenceString('>')
returns ">
"
codePoint
- the Unicode code point to encode.
getCharacterReferenceString(int codePoint)
,
getDecimalCharacterReferenceString(int codePoint)
public java.lang.String getUnicodeText()
This is equivalent to getUnicodeText(getCodePoint())
.
CharacterReference.parse(">").getUnicodeText()
returns "U+003E
"
getUnicodeText(int codePoint)
public static java.lang.String getUnicodeText(int codePoint)
CharacterReference.getUnicodeText('>')
returns "U+003E
"
codePoint
- the Unicode code point.
public static CharacterReference parse(java.lang.CharSequence characterReferenceText)
The character reference must be at the start of the given text, but may contain other characters at the end.
The getEnd()
method can be used on the resulting object to determine at which character position the character reference ended.
If the text does not represent a valid character reference, this method returns null
.
To decode all character references in a given text, use the decode(CharSequence encodedText)
method instead.
CharacterReference.parse(">").getChar()
returns '>
'
characterReferenceText
- the text containing a single encoded character reference.
CharacterReference
object representing the specified text, or null
if the text does not represent a valid character reference.decode(CharSequence encodedText)
public static int getCodePointFromCharacterReferenceString(java.lang.CharSequence characterReferenceText)
The character reference must be at the start of the given text, but may contain other characters at the end.
If the text does not represent a valid character reference, this method returns INVALID_CODE_POINT
.
CharacterReference.getCodePointFromCharacterReferenceString(">")
returns 38
characterReferenceText
- the text containing a single encoded character reference.
INVALID_CODE_POINT
if the text does not represent a valid character reference.public static final boolean requiresEncoding(char ch)
This is the case if a character entity reference exists for the character, or the Unicode code point value is greater than U+007F.
The only exception to this is an apostrophe (U+0027),
which only returns true
if the static ApostropheEncoded
property is currently set to true
.
ch
- the character to be tested.
true
if the specified character would need to be encoded in HTML text, otherwise false
.
|
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |