1/* 2 * Copyright (c) 2012, 2016, Oracle and/or its affiliates. All rights reserved. 3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. 4 * 5 * This code is free software; you can redistribute it and/or modify it 6 * under the terms of the GNU General Public License version 2 only, as 7 * published by the Free Software Foundation. Oracle designates this 8 * particular file as subject to the "Classpath" exception as provided 9 * by Oracle in the LICENSE file that accompanied this code. 10 * 11 * This code is distributed in the hope that it will be useful, but WITHOUT 12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License 14 * version 2 for more details (a copy is included in the LICENSE file that 15 * accompanied this code). 16 * 17 * You should have received a copy of the GNU General Public License version 18 * 2 along with this work; if not, write to the Free Software Foundation, 19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. 20 * 21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA 22 * or visit www.oracle.com if you need additional information or have any 23 * questions. 24 */ 25 26package com.sun.tools.javac.parser; 27 28import com.sun.tools.javac.parser.Tokens.TokenKind; 29import com.sun.tools.javac.tree.JCTree; 30import com.sun.tools.javac.util.List; 31import com.sun.tools.javac.util.ListBuffer; 32import com.sun.tools.javac.util.Log; 33import com.sun.tools.javac.util.Name; 34 35/** 36 * A utility class to parse a string in a doc comment containing a 37 * reference to an API element, such as a type, field or method. 38 * 39 * <p><b>This is NOT part of any supported API. 40 * If you write code that depends on this, you do so at your own risk. 41 * This code and its internal interfaces are subject to change or 42 * deletion without notice.</b> 43 */ 44public class ReferenceParser { 45 /** 46 * An object to contain the result of parsing a reference to an API element. 47 * Any, but not all, of the member fields may be null. 48 */ 49 static public class Reference { 50 /** The type, if any, in the signature. */ 51 public final JCTree qualExpr; 52 /** The member name, if any, in the signature. */ 53 public final Name member; 54 /** The parameter types, if any, in the signature. */ 55 public final List<JCTree> paramTypes; 56 57 Reference(JCTree qualExpr, Name member, List<JCTree> paramTypes) { 58 this.qualExpr = qualExpr; 59 this.member = member; 60 this.paramTypes = paramTypes; 61 } 62 } 63 64 /** 65 * An exception that indicates an error occurred while parsing a signature. 66 */ 67 static public class ParseException extends Exception { 68 private static final long serialVersionUID = 0; 69 ParseException(String message) { 70 super(message); 71 } 72 } 73 74 private final ParserFactory fac; 75 76 /** 77 * Create a parser object to parse reference signatures. 78 * @param fac a factory for parsing Java source code. 79 */ 80 public ReferenceParser(ParserFactory fac) { 81 this.fac = fac; 82 } 83 84 /** 85 * Parse a reference to an API element as may be found in doc comment. 86 * @param sig the signature to be parsed 87 * @return a {@code Reference} object containing the result of parsing the signature 88 * @throws ParseException if there is an error while parsing the signature 89 */ 90 public Reference parse(String sig) throws ParseException { 91 92 // Break sig apart into qualifiedExpr member paramTypes. 93 JCTree qualExpr; 94 Name member; 95 List<JCTree> paramTypes; 96 97 Log.DeferredDiagnosticHandler deferredDiagnosticHandler 98 = new Log.DeferredDiagnosticHandler(fac.log); 99 100 try { 101 int hash = sig.indexOf("#"); 102 int lparen = sig.indexOf("(", hash + 1); 103 if (hash == -1) { 104 if (lparen == -1) { 105 qualExpr = parseType(sig); 106 member = null; 107 } else { 108 qualExpr = null; 109 member = parseMember(sig.substring(0, lparen)); 110 } 111 } else { 112 qualExpr = (hash == 0) ? null : parseType(sig.substring(0, hash)); 113 if (lparen == -1) 114 member = parseMember(sig.substring(hash + 1)); 115 else 116 member = parseMember(sig.substring(hash + 1, lparen)); 117 } 118 119 if (lparen < 0) { 120 paramTypes = null; 121 } else { 122 int rparen = sig.indexOf(")", lparen); 123 if (rparen != sig.length() - 1) 124 throw new ParseException("dc.ref.bad.parens"); 125 paramTypes = parseParams(sig.substring(lparen + 1, rparen)); 126 } 127 128 if (!deferredDiagnosticHandler.getDiagnostics().isEmpty()) 129 throw new ParseException("dc.ref.syntax.error"); 130 131 } finally { 132 fac.log.popDiagnosticHandler(deferredDiagnosticHandler); 133 } 134 135 return new Reference(qualExpr, member, paramTypes); 136 } 137 138 private JCTree parseType(String s) throws ParseException { 139 JavacParser p = fac.newParser(s, false, false, false); 140 JCTree tree = p.parseType(); 141 if (p.token().kind != TokenKind.EOF) 142 throw new ParseException("dc.ref.unexpected.input"); 143 return tree; 144 } 145 146 private Name parseMember(String s) throws ParseException { 147 JavacParser p = fac.newParser(s, false, false, false); 148 Name name = p.ident(); 149 if (p.token().kind != TokenKind.EOF) 150 throw new ParseException("dc.ref.unexpected.input"); 151 return name; 152 } 153 154 private List<JCTree> parseParams(String s) throws ParseException { 155 if (s.trim().isEmpty()) 156 return List.nil(); 157 158 JavacParser p = fac.newParser(s.replace("...", "[]"), false, false, false); 159 ListBuffer<JCTree> paramTypes = new ListBuffer<>(); 160 paramTypes.add(p.parseType()); 161 162 if (p.token().kind == TokenKind.IDENTIFIER) 163 p.nextToken(); 164 165 while (p.token().kind == TokenKind.COMMA) { 166 p.nextToken(); 167 paramTypes.add(p.parseType()); 168 169 if (p.token().kind == TokenKind.IDENTIFIER) 170 p.nextToken(); 171 } 172 173 if (p.token().kind != TokenKind.EOF) 174 throw new ParseException("dc.ref.unexpected.input"); 175 176 return paramTypes.toList(); 177 } 178} 179