* This provides a human readable version of the segment content that is modelled on the way * Mozilla Thunderbird and other email clients provide an automatic conversion of * HTML content to text in their alternative MIME encoding of emails. *
* The output using default settings complies with the "text/plain; format=flowed" (DelSp=No) protocol described in * RFC3676. *
* Many properties are available to customise the output, possibly the most significant of which being {@link #setMaxLineLength(int) MaxLineLength}. * See the individual property descriptions for details. *
* Use one of the following methods to obtain the output: *
* The rendering of some constructs, especially tables, is very rudimentary. * No attempt is made to render nested tables properly, except to ensure that all of the text content is included in the output. *
* Rendering an entire {@link Source} object performs a {@linkplain Source#fullSequentialParse() full sequential parse} automatically. *
* Any aspect of the algorithm not specifically mentioned here is subject to change without notice in future versions. *
* To extract pure text without any rendering of the markup, use the {@link TextExtractor} class instead.
*/
public class Renderer implements CharStreamSource {
private final Segment rootSegment;
private int maxLineLength=76;
private String newLine="\r\n";
private boolean includeHyperlinkURLs=true;
private boolean decorateFontStyles=false;
private boolean convertNonBreakingSpaces=Config.ConvertNonBreakingSpaces;
private int blockIndentSize=4;
private int listIndentSize=6;
private char[] listBullets=new char[] {'*','o','+','#'};
private String tableCellSeparator=" \t";
/**
* Constructs a new Renderer based on the specified {@link Segment}.
* @param segment the segment containing the HTML to be rendered.
* @see Segment#getRenderer()
*/
public Renderer(final Segment segment) {
rootSegment=segment;
}
// Documentation inherited from CharStreamSource
public void writeTo(final Writer writer) throws IOException {
appendTo(writer);
writer.flush();
}
// Documentation inherited from CharStreamSource
public void appendTo(final Appendable appendable) throws IOException {
new Processor(this,rootSegment,getMaxLineLength(),getNewLine(),getIncludeHyperlinkURLs(),getDecorateFontStyles(),getConvertNonBreakingSpaces(),getBlockIndentSize(),getListIndentSize(),getListBullets(),getTableCellSeparator()).appendTo(appendable);
}
// Documentation inherited from CharStreamSource
public long getEstimatedMaximumOutputLength() {
return rootSegment.length();
}
// Documentation inherited from CharStreamSource
public String toString() {
return CharStreamSourceUtil.toString(this);
}
/**
* Sets the column at which lines are to be wrapped.
*
* Lines that would otherwise exceed this length are wrapped onto a new line at a word boundary. *
* A Line may still exceed this length if it consists of a single word, where the length of the word plus the line indent exceeds the maximum length. * In this case the line is wrapped immediately after the end of the word. *
* The default value is 76, which reflects the maximum line length for sending
* email data specified in RFC2049 section 3.5.
*
* @param maxLineLength the column at which lines are to be wrapped.
* @return this Renderer instance, allowing multiple property setting methods to be chained in a single statement.
* @see #getMaxLineLength()
*/
public Renderer setMaxLineLength(final int maxLineLength) {
this.maxLineLength=maxLineLength;
return this;
}
/**
* Returns the column at which lines are to be wrapped.
*
* See the {@link #setMaxLineLength(int)} method for a full description of this property. * * @return the column at which lines are to be wrapped. */ public int getMaxLineLength() { return maxLineLength; } /** * Sets the string to be used to represent a newline in the output. *
* The default value is "\r\n" (CR+LF) regardless of the platform on which the library is running.
* This is so that the default configuration produces valid
* MIME plain/text output, which mandates the use of CR+LF for line breaks.
*
* Specifying a null argument causes the output to use same new line string as is used in the source document, which is
* determined via the {@link Source#getNewLine()} method.
* If the source document does not contain any new lines, a "best guess" is made by either taking the new line string of a previously parsed document,
* or using the value from the static {@link Config#NewLine} property.
*
* @param newLine the string to be used to represent a newline in the output, may be null.
* @return this Renderer instance, allowing multiple property setting methods to be chained in a single statement.
* @see #getNewLine()
*/
public Renderer setNewLine(final String newLine) {
this.newLine=newLine;
return this;
}
/**
* Returns the string to be used to represent a newline in the output.
*
* See the {@link #setNewLine(String)} method for a full description of this property. * * @return the string to be used to represent a newline in the output. */ public String getNewLine() { if (newLine==null) newLine=rootSegment.source.getBestGuessNewLine(); return newLine; } /** * Sets whether hyperlink URL's are included in the output. *
* The default value is true.
*
* When this property is true, the URL of each hyperlink is included in the output as determined by the implementation of the
* {@link #renderHyperlinkURL(StartTag)} method.
*
*
* Assuming the default implementation of {@link #renderHyperlinkURL(StartTag)}, when this property is true, the following HTML:
*
* <a href="http://jericho.htmlparser.net/">Jericho HTML Parser</a>
*
* produces the following output:
*
* Jericho HTML Parser <http://jericho.htmlparser.net/>
*
* Renderer instance, allowing multiple property setting methods to be chained in a single statement.
* @see #getIncludeHyperlinkURLs()
*/
public Renderer setIncludeHyperlinkURLs(final boolean includeHyperlinkURLs) {
this.includeHyperlinkURLs=includeHyperlinkURLs;
return this;
}
/**
* Indicates whether hyperlink URL's are included in the output.
*
* See the {@link #setIncludeHyperlinkURLs(boolean)} method for a full description of this property.
*
* @return true if hyperlink URL's are included in the output, otherwise false.
*/
public boolean getIncludeHyperlinkURLs() {
return includeHyperlinkURLs;
}
/**
* Renders the hyperlink URL from the specified {@link StartTag}.
*
* A return value of null indicates that the hyperlink URL should not be rendered at all.
*
* The default implementation of this method returns null if the href attribute of the specified start tag
* is '#', starts with "javascript:", or is missing.
* In all other cases it returns the value of the href attribute enclosed in angle brackets.
*
* See the documentation of the {@link #setIncludeHyperlinkURLs(boolean)} method for an example of how a hyperlink is rendered by the default implementation. *
* This method can be overridden in a subclass to customise the rendering of hyperlink URLs. *
* Rendering of hyperlink URLs can be disabled completely without overriding this method by setting the
* {@link #setIncludeHyperlinkURLs(boolean) IncludeHyperlinkURLs} property to false.
*
*
* Renderer renderer=new Renderer(segment) {
* public String renderHyperlinkURL(StartTag startTag) {
* String href=startTag.getAttributeValue("href");
* if (href==null || href.equals("#") || href.startsWith("javascript:")) return null;
* return href;
* }
* };
* String renderedSegment=renderer.toString();
*
* null.
* @return The rendered hyperlink URL from the specified {@link StartTag}, or null if the hyperlink URL should not be rendered.
*/
public String renderHyperlinkURL(final StartTag startTag) {
final String href=startTag.getAttributeValue("href");
if (href==null || href.equals("#") || href.startsWith("javascript:")) return null;
return '<'+href+'>';
}
/**
* Sets whether decoration characters are to be included around the content of some
* font style elements and
* phrase elements.
*
* The default value is false.
*
* Below is a table summarising the decorated elements. *
* *
| Elements | Character | Example Output |
|---|---|---|
| {@link HTMLElementName#B B} and {@link HTMLElementName#STRONG STRONG} | * | *bold text* |
| {@link HTMLElementName#I I} and {@link HTMLElementName#EM EM} | / | /italic text/ |
| {@link HTMLElementName#U U} | _ | _underlined text_ |
| {@link HTMLElementName#CODE CODE} | | | |code| |
Renderer instance, allowing multiple property setting methods to be chained in a single statement.
* @see #getDecorateFontStyles()
*/
public Renderer setDecorateFontStyles(final boolean decorateFontStyles) {
this.decorateFontStyles=decorateFontStyles;
return this;
}
/**
* Indicates whether decoration characters are to be included around the content of some
* font style elements and
* phrase elements.
*
* See the {@link #setDecorateFontStyles(boolean)} method for a full description of this property.
*
* @return true if decoration characters are to be included around the content of some font style elements, otherwise false.
*/
public boolean getDecorateFontStyles() {
return decorateFontStyles;
}
/**
* Sets whether non-breaking space ({@link CharacterEntityReference#_nbsp }) character entity references are converted to spaces.
*
* The default value is that of the static {@link Config#ConvertNonBreakingSpaces} property at the time the Renderer is instantiated.
*
* @param convertNonBreakingSpaces specifies whether non-breaking space ({@link CharacterEntityReference#_nbsp }) character entity references are converted to spaces.
* @return this Renderer instance, allowing multiple property setting methods to be chained in a single statement.
* @see #getConvertNonBreakingSpaces()
*/
public Renderer setConvertNonBreakingSpaces(boolean convertNonBreakingSpaces) {
this.convertNonBreakingSpaces=convertNonBreakingSpaces;
return this;
}
/**
* Indicates whether non-breaking space ({@link CharacterEntityReference#_nbsp }) character entity references are converted to spaces.
*
* See the {@link #setConvertNonBreakingSpaces(boolean)} method for a full description of this property.
*
* @return true if non-breaking space ({@link CharacterEntityReference#_nbsp }) character entity references are converted to spaces, otherwise false.
*/
public boolean getConvertNonBreakingSpaces() {
return convertNonBreakingSpaces;
}
/**
* Sets the size of the indent to be used for anything other than {@link HTMLElementName#LI LI} elements.
*
* At present this applies to {@link HTMLElementName#BLOCKQUOTE BLOCKQUOTE} and {@link HTMLElementName#DD DD} elements. *
* The default value is 4.
*
* @param blockIndentSize the size of the indent.
* @return this Renderer instance, allowing multiple property setting methods to be chained in a single statement.
* @see #getBlockIndentSize()
*/
public Renderer setBlockIndentSize(final int blockIndentSize) {
this.blockIndentSize=blockIndentSize;
return this;
}
/**
* Returns the size of the indent to be used for anything other than {@link HTMLElementName#LI LI} elements.
*
* See the {@link #setBlockIndentSize(int)} method for a full description of this property. * * @return the size of the indent to be used for anything other than {@link HTMLElementName#LI LI} elements. */ public int getBlockIndentSize() { return blockIndentSize; } /** * Sets the size of the indent to be used for {@link HTMLElementName#LI LI} elements. *
* The default value is 6.
*
* This applies to {@link HTMLElementName#LI LI} elements inside both {@link HTMLElementName#UL UL} and {@link HTMLElementName#OL OL} elements. *
* The bullet or number of the list item is included as part of the indent.
*
* @param listIndentSize the size of the indent.
* @return this Renderer instance, allowing multiple property setting methods to be chained in a single statement.
* @see #getListIndentSize()
*/
public Renderer setListIndentSize(final int listIndentSize) {
this.listIndentSize=listIndentSize;
return this;
}
/**
* Returns the size of the indent to be used for {@link HTMLElementName#LI LI} elements.
*
* See the {@link #setListIndentSize(int)} method for a full description of this property. * * @return the size of the indent to be used for {@link HTMLElementName#LI LI} elements. */ public int getListIndentSize() { return listIndentSize; } /** * Sets the bullet characters to use for list items inside {@link HTMLElementName#UL UL} elements. *
* The values in the default array are *, o, + and #.
*
* If the nesting of rendered lists goes deeper than the length of this array, the bullet characters start repeating from the first in the array. *
* WARNING: If any of the characters in the default array are modified, this will affect all other instances of this class using the default array.
*
* @param listBullets an array of characters to be used as bullets, must have at least one entry.
* @return this Renderer instance, allowing multiple property setting methods to be chained in a single statement.
* @see #getListBullets()
*/
public Renderer setListBullets(final char[] listBullets) {
if (listBullets==null || listBullets.length==0) throw new IllegalArgumentException("listBullets argument must be an array of at least one character");
this.listBullets=listBullets;
return this;
}
/**
* Returns the bullet characters to use for list items inside {@link HTMLElementName#UL UL} elements.
*
* See the {@link #setListBullets(char[])} method for a full description of this property. * * @return the bullet characters to use for list items inside {@link HTMLElementName#UL UL} elements. */ public char[] getListBullets() { return listBullets; } /** * Sets the string that is to separate table cells. *
* The default value is " \t" (a space followed by a tab).
*
* @param tableCellSeparator the string that is to separate table cells.
* @return this Renderer instance, allowing multiple property setting methods to be chained in a single statement.
* @see #getTableCellSeparator()
*/
public Renderer setTableCellSeparator(final String tableCellSeparator) {
this.tableCellSeparator=tableCellSeparator;
return this;
}
/**
* Returns the string that is to separate table cells.
*
* See the {@link #setTableCellSeparator(String)} method for a full description of this property.
*
* @return the string that is to separate table cells.
*/
public String getTableCellSeparator() {
return tableCellSeparator;
}
/** This class does the actual work, but is first passed final copies of all the parameters for efficiency. */
private static final class Processor {
private final Renderer renderer;
private final Segment rootSegment;
private final Source source;
private final int maxLineLength;
private final String newLine;
private final boolean includeHyperlinkURLs;
private final boolean decorateFontStyles;
private final boolean convertNonBreakingSpaces;
private final int blockIndentSize;
private final int listIndentSize;
private final char[] listBullets;
private final String tableCellSeparator;
private Appendable appendable;
private int renderedIndex; // keeps track of where rendering is up to in case of overlapping elements
private boolean atStartOfLine;
private int col;
private int blockIndentLevel;
private int listIndentLevel;
private int blockVerticalMargin; // minimum number of blank lines to output at the current block boundary, or NO_MARGIN (-1) if we are not currently at a block boundary.
private boolean preformatted;
private boolean lastCharWhiteSpace;
private boolean ignoreInitialWhitespace;
private boolean bullet;
private int listBulletNumber;
private static final int NO_MARGIN=-1;
private static final int UNORDERED_LIST=-1;
private static Map