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