jdk.internal.shellsupport.doc.JavadocFormatter Maven / Gradle / Ivy
Go to download
Show more of this group Show more artifacts with this name
Show all versions of javac Show documentation
Show all versions of javac Show documentation
A repackaged copy of javac for Error Prone to depend on
/*
* Copyright (c) 2016, Oracle and/or its affiliates. All rights reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
* under the terms of the GNU General Public License version 2 only, as
* published by the Free Software Foundation. Oracle designates this
* particular file as subject to the "Classpath" exception as provided
* by Oracle in the LICENSE file that accompanied this code.
*
* This code 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 General Public License
* version 2 for more details (a copy is included in the LICENSE file that
* accompanied this code).
*
* You should have received a copy of the GNU General Public License version
* 2 along with this work; if not, write to the Free Software Foundation,
* Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
*
* Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
* or visit www.oracle.com if you need additional information or have any
* questions.
*/
package jdk.internal.shellsupport.doc;
import java.io.IOException;
import java.net.URI;
import java.net.URISyntaxException;
import java.util.ArrayList;
import java.util.Arrays;
import java.util.Collections;
import java.util.IdentityHashMap;
import java.util.LinkedHashMap;
import java.util.List;
import java.util.Map;
import java.util.ResourceBundle;
import java.util.Stack;
import javax.lang.model.element.Name;
import javax.tools.JavaFileObject.Kind;
import javax.tools.SimpleJavaFileObject;
import javax.tools.ToolProvider;
import com.sun.source.doctree.AttributeTree;
import com.sun.source.doctree.DocCommentTree;
import com.sun.source.doctree.DocTree;
import com.sun.source.doctree.EndElementTree;
import com.sun.source.doctree.EntityTree;
import com.sun.source.doctree.InlineTagTree;
import com.sun.source.doctree.LinkTree;
import com.sun.source.doctree.LiteralTree;
import com.sun.source.doctree.ParamTree;
import com.sun.source.doctree.ReturnTree;
import com.sun.source.doctree.StartElementTree;
import com.sun.source.doctree.TextTree;
import com.sun.source.doctree.ThrowsTree;
import com.sun.source.util.DocTreeScanner;
import com.sun.source.util.DocTrees;
import com.sun.source.util.JavacTask;
import com.sun.tools.doclint.Entity;
import com.sun.tools.doclint.HtmlTag;
import com.sun.tools.javac.util.DefinedBy;
import com.sun.tools.javac.util.DefinedBy.Api;
import com.sun.tools.javac.util.StringUtils;
/**A javadoc to plain text formatter.
*
*/
public class JavadocFormatter {
private static final String CODE_RESET = "\033[0m";
private static final String CODE_HIGHLIGHT = "\033[1m";
private static final String CODE_UNDERLINE = "\033[4m";
private final int lineLimit;
private final boolean escapeSequencesSupported;
/** Construct the formatter.
*
* @param lineLimit maximum line length
* @param escapeSequencesSupported whether escape sequences are supported
*/
public JavadocFormatter(int lineLimit, boolean escapeSequencesSupported) {
this.lineLimit = lineLimit;
this.escapeSequencesSupported = escapeSequencesSupported;
}
private static final int MAX_LINE_LENGTH = 95;
private static final int SHORTEST_LINE = 30;
private static final int INDENT = 4;
/**Format javadoc to plain text.
*
* @param header element caption that should be used
* @param javadoc to format
* @return javadoc formatted to plain text
*/
public String formatJavadoc(String header, String javadoc) {
try {
StringBuilder result = new StringBuilder();
result.append(escape(CODE_HIGHLIGHT)).append(header).append(escape(CODE_RESET)).append("\n");
if (javadoc == null) {
return result.toString();
}
JavacTask task = (JavacTask) ToolProvider.getSystemJavaCompiler().getTask(null, null, null, null, null, null);
DocTrees trees = DocTrees.instance(task);
DocCommentTree docComment = trees.getDocCommentTree(new SimpleJavaFileObject(new URI("mem://doc.html"), Kind.HTML) {
@Override @DefinedBy(Api.COMPILER)
public CharSequence getCharContent(boolean ignoreEncodingErrors) throws IOException {
return "" + javadoc + "";
}
});
new FormatJavadocScanner(result, task).scan(docComment, null);
addNewLineIfNeeded(result);
return result.toString();
} catch (URISyntaxException ex) {
throw new InternalError("Unexpected exception", ex);
}
}
private class FormatJavadocScanner extends DocTreeScanner {
private final StringBuilder result;
private final JavacTask task;
private int reflownTo;
private int indent;
private int limit = Math.min(lineLimit, MAX_LINE_LENGTH);
private boolean pre;
private Map tableColumns;
public FormatJavadocScanner(StringBuilder result, JavacTask task) {
this.result = result;
this.task = task;
}
@Override @DefinedBy(Api.COMPILER_TREE)
public Object visitDocComment(DocCommentTree node, Object p) {
tableColumns = countTableColumns(node);
reflownTo = result.length();
scan(node.getFirstSentence(), p);
scan(node.getBody(), p);
reflow(result, reflownTo, indent, limit);
for (Sections current : docSections.keySet()) {
boolean seenAny = false;
for (DocTree t : node.getBlockTags()) {
if (current.matches(t)) {
if (!seenAny) {
seenAny = true;
if (result.charAt(result.length() - 1) != '\n')
result.append("\n");
result.append("\n");
result.append(escape(CODE_UNDERLINE))
.append(docSections.get(current))
.append(escape(CODE_RESET))
.append("\n");
}
scan(t, null);
}
}
}
return null;
}
@Override @DefinedBy(Api.COMPILER_TREE)
public Object visitText(TextTree node, Object p) {
String text = node.getBody();
if (!pre) {
text = text.replaceAll("[ \t\r\n]+", " ").trim();
if (text.isEmpty()) {
text = " ";
}
} else {
text = text.replaceAll("\n", "\n" + indentString(indent));
}
result.append(text);
return null;
}
@Override @DefinedBy(Api.COMPILER_TREE)
public Object visitLink(LinkTree node, Object p) {
if (!node.getLabel().isEmpty()) {
scan(node.getLabel(), p);
} else {
result.append(node.getReference().getSignature());
}
return null;
}
@Override @DefinedBy(Api.COMPILER_TREE)
public Object visitParam(ParamTree node, Object p) {
return formatDef(node.getName().getName(), node.getDescription());
}
@Override @DefinedBy(Api.COMPILER_TREE)
public Object visitThrows(ThrowsTree node, Object p) {
return formatDef(node.getExceptionName().getSignature(), node.getDescription());
}
public Object formatDef(CharSequence name, List description) {
result.append(name);
result.append(" - ");
reflownTo = result.length();
indent = name.length() + 3;
if (limit - indent < SHORTEST_LINE) {
result.append("\n");
result.append(indentString(INDENT));
indent = INDENT;
reflownTo += INDENT;
}
try {
return scan(description, null);
} finally {
reflow(result, reflownTo, indent, limit);
result.append("\n");
}
}
@Override @DefinedBy(Api.COMPILER_TREE)
public Object visitLiteral(LiteralTree node, Object p) {
return scan(node.getBody(), p);
}
@Override @DefinedBy(Api.COMPILER_TREE)
public Object visitReturn(ReturnTree node, Object p) {
reflownTo = result.length();
try {
return super.visitReturn(node, p);
} finally {
reflow(result, reflownTo, 0, limit);
}
}
Stack listStack = new Stack<>();
Stack defStack = new Stack<>();
Stack tableStack = new Stack<>();
Stack> cellsStack = new Stack<>();
Stack> headerStack = new Stack<>();
@Override @DefinedBy(Api.COMPILER_TREE)
public Object visitStartElement(StartElementTree node, Object p) {
switch (getHtmlTag(node.getName())) {
case P:
if (lastNode!= null && lastNode.getKind() == DocTree.Kind.START_ELEMENT &&
HtmlTag.get(((StartElementTree) lastNode).getName()) == HtmlTag.LI) {
//ignore
break;
}
reflowTillNow();
addNewLineIfNeeded(result);
result.append(indentString(indent));
reflownTo = result.length();
break;
case BLOCKQUOTE:
reflowTillNow();
indent += INDENT;
break;
case PRE:
reflowTillNow();
pre = true;
break;
case UL:
reflowTillNow();
listStack.push(-1);
indent += INDENT;
break;
case OL:
reflowTillNow();
listStack.push(1);
indent += INDENT;
break;
case DL:
reflowTillNow();
defStack.push(indent);
break;
case LI:
reflowTillNow();
if (!listStack.empty()) {
addNewLineIfNeeded(result);
int top = listStack.pop();
if (top == (-1)) {
result.append(indentString(indent - 2));
result.append("* ");
} else {
result.append(indentString(indent - 3));
result.append("" + top++ + ". ");
}
listStack.push(top);
reflownTo = result.length();
}
break;
case DT:
reflowTillNow();
if (!defStack.isEmpty()) {
addNewLineIfNeeded(result);
indent = defStack.peek();
result.append(escape(CODE_HIGHLIGHT));
}
break;
case DD:
reflowTillNow();
if (!defStack.isEmpty()) {
if (indent == defStack.peek()) {
result.append(escape(CODE_RESET));
}
addNewLineIfNeeded(result);
indent = defStack.peek() + INDENT;
result.append(indentString(indent));
}
break;
case H1: case H2: case H3:
case H4: case H5: case H6:
reflowTillNow();
addNewLineIfNeeded(result);
result.append("\n")
.append(escape(CODE_UNDERLINE));
reflownTo = result.length();
break;
case TABLE:
int columns = tableColumns.get(node);
if (columns == 0) {
break; //broken input
}
reflowTillNow();
addNewLineIfNeeded(result);
reflownTo = result.length();
tableStack.push(limit);
limit = (limit - 1) / columns - 3;
for (int sep = 0; sep < (limit + 3) * columns + 1; sep++) {
result.append("-");
}
result.append("\n");
break;
case TR:
if (cellsStack.size() >= tableStack.size()) {
//unclosed :
handleEndElement(node.getName());
}
cellsStack.push(new ArrayList<>());
headerStack.push(new ArrayList<>());
break;
case TH:
case TD:
if (cellsStack.isEmpty()) {
//broken code
break;
}
reflowTillNow();
result.append("\n");
reflownTo = result.length();
cellsStack.peek().add(result.length());
headerStack.peek().add(HtmlTag.get(node.getName()) == HtmlTag.TH);
break;
case IMG:
for (DocTree attr : node.getAttributes()) {
if (attr.getKind() != DocTree.Kind.ATTRIBUTE) {
continue;
}
AttributeTree at = (AttributeTree) attr;
if ("alt".equals(StringUtils.toLowerCase(at.getName().toString()))) {
addSpaceIfNeeded(result);
scan(at.getValue(), null);
addSpaceIfNeeded(result);
break;
}
}
break;
default:
addSpaceIfNeeded(result);
break;
}
return null;
}
@Override @DefinedBy(Api.COMPILER_TREE)
public Object visitEndElement(EndElementTree node, Object p) {
handleEndElement(node.getName());
return super.visitEndElement(node, p);
}
private void handleEndElement(Name name) {
switch (getHtmlTag(name)) {
case BLOCKQUOTE:
indent -= INDENT;
break;
case PRE:
pre = false;
addNewLineIfNeeded(result);
reflownTo = result.length();
break;
case UL: case OL:
if (listStack.isEmpty()) { //ignore stray closing tag
break;
}
reflowTillNow();
listStack.pop();
indent -= INDENT;
addNewLineIfNeeded(result);
break;
case DL:
if (defStack.isEmpty()) {//ignore stray closing tag
break;
}
reflowTillNow();
if (indent == defStack.peek()) {
result.append(escape(CODE_RESET));
}
indent = defStack.pop();
addNewLineIfNeeded(result);
break;
case H1: case H2: case H3:
case H4: case H5: case H6:
reflowTillNow();
result.append(escape(CODE_RESET))
.append("\n");
reflownTo = result.length();
break;
case TABLE:
if (cellsStack.size() >= tableStack.size()) {
//unclosed :
handleEndElement(task.getElements().getName("tr"));
}
if (tableStack.isEmpty()) {
break;
}
limit = tableStack.pop();
break;
case TR:
if (cellsStack.isEmpty()) {
break;
}
reflowTillNow();
List cells = cellsStack.pop();
List headerFlags = headerStack.pop();
List content = new ArrayList<>();
int maxLines = 0;
result.append("\n");
while (!cells.isEmpty()) {
int currentCell = cells.remove(cells.size() - 1);
String[] lines = result.substring(currentCell, result.length()).split("\n");
result.delete(currentCell - 1, result.length());
content.add(lines);
maxLines = Math.max(maxLines, lines.length);
}
Collections.reverse(content);
for (int line = 0; line < maxLines; line++) {
for (int column = 0; column < content.size(); column++) {
String[] lines = content.get(column);
String currentLine = line < lines.length ? lines[line] : "";
result.append("| ");
boolean header = headerFlags.get(column);
if (header) {
result.append(escape(CODE_HIGHLIGHT));
}
result.append(currentLine);
if (header) {
result.append(escape(CODE_RESET));
}
int padding = limit - currentLine.length();
if (padding > 0)
result.append(indentString(padding));
result.append(" ");
}
result.append("|\n");
}
for (int sep = 0; sep < (limit + 3) * content.size() + 1; sep++) {
result.append("-");
}
result.append("\n");
reflownTo = result.length();
break;
case TD:
case TH:
break;
default:
addSpaceIfNeeded(result);
break;
}
}
@Override @DefinedBy(Api.COMPILER_TREE)
public Object visitEntity(EntityTree node, Object p) {
String name = node.getName().toString();
int code = -1;
if (name.startsWith("#")) {
try {
int v = StringUtils.toLowerCase(name).startsWith("#x")
? Integer.parseInt(name.substring(2), 16)
: Integer.parseInt(name.substring(1), 10);
if (Entity.isValid(v)) {
code = v;
}
} catch (NumberFormatException ex) {
//ignore
}
} else {
Entity entity = Entity.get(name);
if (entity != null) {
code = entity.code;
}
}
if (code != (-1)) {
result.appendCodePoint(code);
} else {
result.append(node.toString());
}
return super.visitEntity(node, p);
}
private DocTree lastNode;
@Override @DefinedBy(Api.COMPILER_TREE)
public Object scan(DocTree node, Object p) {
if (node instanceof InlineTagTree) {
addSpaceIfNeeded(result);
}
try {
return super.scan(node, p);
} finally {
if (node instanceof InlineTagTree) {
addSpaceIfNeeded(result);
}
lastNode = node;
}
}
private void reflowTillNow() {
while (result.length() > 0 && result.charAt(result.length() - 1) == ' ')
result.delete(result.length() - 1, result.length());
reflow(result, reflownTo, indent, limit);
reflownTo = result.length();
}
};
private String escape(String sequence) {
return this.escapeSequencesSupported ? sequence : "";
}
private static final Map docSections = new LinkedHashMap<>();
static {
ResourceBundle bundle =
ResourceBundle.getBundle("jdk.internal.shellsupport.doc.resources.javadocformatter");
docSections.put(Sections.TYPE_PARAMS, bundle.getString("CAP_TypeParameters"));
docSections.put(Sections.PARAMS, bundle.getString("CAP_Parameters"));
docSections.put(Sections.RETURNS, bundle.getString("CAP_Returns"));
docSections.put(Sections.THROWS, bundle.getString("CAP_Thrown_Exceptions"));
}
private static String indentString(int indent) {
char[] content = new char[indent];
Arrays.fill(content, ' ');
return new String(content);
}
private static void reflow(StringBuilder text, int from, int indent, int limit) {
int lineStart = from;
while (lineStart > 0 && text.charAt(lineStart - 1) != '\n') {
lineStart--;
}
int lineChars = from - lineStart;
int pointer = from;
int lastSpace = -1;
while (pointer < text.length()) {
if (text.charAt(pointer) == ' ')
lastSpace = pointer;
if (lineChars >= limit) {
if (lastSpace != (-1)) {
text.setCharAt(lastSpace, '\n');
text.insert(lastSpace + 1, indentString(indent));
lineChars = indent + pointer - lastSpace - 1;
pointer += indent;
lastSpace = -1;
}
}
lineChars++;
pointer++;
}
}
private static void addNewLineIfNeeded(StringBuilder text) {
if (text.length() > 0 && text.charAt(text.length() - 1) != '\n') {
text.append("\n");
}
}
private static void addSpaceIfNeeded(StringBuilder text) {
if (text.length() == 0)
return ;
char last = text.charAt(text.length() - 1);
if (last != ' ' && last != '\n') {
text.append(" ");
}
}
private static HtmlTag getHtmlTag(Name name) {
HtmlTag tag = HtmlTag.get(name);
return tag != null ? tag : HtmlTag.HTML; //using HtmlTag.HTML as default no-op value
}
private static Map countTableColumns(DocCommentTree dct) {
Map result = new IdentityHashMap<>();
new DocTreeScanner() {
private StartElementTree currentTable;
private int currentMaxColumns;
private int currentRowColumns;
@Override @DefinedBy(Api.COMPILER_TREE)
public Void visitStartElement(StartElementTree node, Void p) {
switch (getHtmlTag(node.getName())) {
case TABLE: currentTable = node; break;
case TR:
currentMaxColumns = Math.max(currentMaxColumns, currentRowColumns);
currentRowColumns = 0;
break;
case TD:
case TH: currentRowColumns++; break;
}
return super.visitStartElement(node, p);
}
@Override @DefinedBy(Api.COMPILER_TREE)
public Void visitEndElement(EndElementTree node, Void p) {
if (HtmlTag.get(node.getName()) == HtmlTag.TABLE) {
closeTable();
}
return super.visitEndElement(node, p);
}
@Override @DefinedBy(Api.COMPILER_TREE)
public Void visitDocComment(DocCommentTree node, Void p) {
try {
return super.visitDocComment(node, p);
} finally {
closeTable();
}
}
private void closeTable() {
if (currentTable != null) {
result.put(currentTable, Math.max(currentMaxColumns, currentRowColumns));
currentTable = null;
}
}
}.scan(dct, null);
return result;
}
private enum Sections {
TYPE_PARAMS {
@Override public boolean matches(DocTree t) {
return t.getKind() == DocTree.Kind.PARAM && ((ParamTree) t).isTypeParameter();
}
},
PARAMS {
@Override public boolean matches(DocTree t) {
return t.getKind() == DocTree.Kind.PARAM && !((ParamTree) t).isTypeParameter();
}
},
RETURNS {
@Override public boolean matches(DocTree t) {
return t.getKind() == DocTree.Kind.RETURN;
}
},
THROWS {
@Override public boolean matches(DocTree t) {
return t.getKind() == DocTree.Kind.THROWS;
}
};
public abstract boolean matches(DocTree t);
}
}
© 2015 - 2024 Weber Informatics LLC | Privacy Policy