/*

 * Copyright (c) 2012, 2019, 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 com.sun.tools.javac.parser;

import java.text.BreakIterator;

import java.util.HashMap;

import java.util.Map;

import com.sun.source.doctree.AttributeTree.ValueKind;

import com.sun.tools.javac.parser.DocCommentParser.TagParser.Kind;

import com.sun.tools.javac.parser.Tokens.Comment;

import com.sun.tools.javac.parser.Tokens.TokenKind;

import com.sun.tools.javac.tree.DCTree;

import com.sun.tools.javac.tree.DCTree.DCAttribute;

import com.sun.tools.javac.tree.DCTree.DCDocComment;

import com.sun.tools.javac.tree.DCTree.DCEndElement;

import com.sun.tools.javac.tree.DCTree.DCEndPosTree;

import com.sun.tools.javac.tree.DCTree.DCErroneous;

import com.sun.tools.javac.tree.DCTree.DCIdentifier;

import com.sun.tools.javac.tree.DCTree.DCReference;

import com.sun.tools.javac.tree.DCTree.DCStartElement;

import com.sun.tools.javac.tree.DCTree.DCText;

import com.sun.tools.javac.tree.DocTreeMaker;

import com.sun.tools.javac.tree.JCTree;

import com.sun.tools.javac.util.DiagnosticSource;

import com.sun.tools.javac.util.List;

import com.sun.tools.javac.util.ListBuffer;

import com.sun.tools.javac.util.Log;

import com.sun.tools.javac.util.Name;

import com.sun.tools.javac.util.Names;

import com.sun.tools.javac.util.Position;

import com.sun.tools.javac.util.StringUtils;

import static com.sun.tools.javac.util.LayoutCharacters.*;

/**

 *

 *  <p><b>This is NOT part of any supported API.

 *  If you write code that depends on this, you do so at your own risk.

 *  This code and its internal interfaces are subject to change or

 *  deletion without notice.</b>

 */

public class DocCommentParser {

    static class ParseException extends Exception {

        private static final long serialVersionUID = 0;

        ParseException(String key) {

            super(key);

        }

    }

    private enum Phase {PREAMBLE, BODY, POSTAMBLE};

    final ParserFactory fac;

    final DiagnosticSource diagSource;

    final Comment comment;

    final DocTreeMaker m;

    final Names names;

    final boolean isFileContent;

    BreakIterator sentenceBreaker;

    /** The input buffer, index of most recent character read,

     *  index of one past last character in buffer.

     */

    protected char[] buf;

    protected int bp;

    protected int buflen;

    /** The current character.

     */

    protected char ch;

    int textStart = -1;

    int lastNonWhite = -1;

    boolean newline = true;

    Map<Name, TagParser> tagParsers;

    public DocCommentParser(ParserFactory fac, DiagnosticSource diagSource,

                            Comment comment, boolean isFileContent) {

        this.fac = fac;

        this.diagSource = diagSource;

        this.comment = comment;

        names = fac.names;

        this.isFileContent = isFileContent;

        m = fac.docTreeMaker;

        initTagParsers();

    }

    public DocCommentParser(ParserFactory fac, DiagnosticSource diagSource, Comment comment) {

        this(fac, diagSource, comment, false);

    }

    public DocCommentParser(ParserFactory fac) {

        this(fac, null, null, false);

    }

    public DCDocComment parse() {

        String c = comment.getText();

        buf = new char[c.length() + 1];

        c.getChars(0, c.length(), buf, 0);

        buf[buf.length - 1] = EOI;

        buflen = buf.length - 1;

        bp = -1;

        nextChar();

        List<DCTree> preamble = isFileContent ? blockContent(Phase.PREAMBLE) : List.nil();

        List<DCTree> body = blockContent(Phase.BODY);

        List<DCTree> tags = blockTags();

        List<DCTree> postamble = isFileContent ? blockContent(Phase.POSTAMBLE) : List.nil();

        int pos = Position.NOPOS;

        if (!preamble.isEmpty())

            pos = preamble.head.pos;

        else if (!body.isEmpty())

            pos = body.head.pos;

        else if (!tags.isEmpty())

            pos = tags.head.pos;

        else if (!postamble.isEmpty())

            pos = postamble.head.pos;

        DCDocComment dc = m.at(pos).newDocCommentTree(comment, body, tags, preamble, postamble);

        return dc;

    }

    void nextChar() {

        ch = buf[bp < buflen ? ++bp : buflen];

        switch (ch) {

            case '\f': case '\n': case '\r':

                newline = true;

        }

    }

    protected List<DCTree> blockContent() {

        return blockContent(Phase.BODY);

    }

    /**

     * Read block content, consisting of text, html and inline tags.

     * Terminated by the end of input, or the beginning of the next block tag:

     * i.e. @ as the first non-whitespace character on a line.

     */

    @SuppressWarnings("fallthrough")

    protected List<DCTree> blockContent(Phase phase) {

        ListBuffer<DCTree> trees = new ListBuffer<>();

        textStart = -1;

        loop:

        while (bp < buflen) {

            switch (ch) {

                case '\n': case '\r': case '\f':

                    newline = true;

                    // fallthrough

                case ' ': case '\t':

                    nextChar();

                    break;

                case '&':

                    entity(trees);

                    break;

                case '<':

                    newline = false;

                    if (isFileContent) {

                        switch (phase) {

                            case PREAMBLE:

                                if (isEndPreamble()) {

                                    trees.add(html());

                                    if (textStart == -1) {

                                        textStart = bp;

                                        lastNonWhite = -1;

                                    }

                                    // mark this as the start, for processing purposes

                                    newline = true;

                                    break loop;

                                }

                                break;

                            case BODY:

                                if (isEndBody()) {

                                    addPendingText(trees, lastNonWhite);

                                    break loop;

                                }

                                break;

                            default:

                                // fallthrough

                        }

                    }

                    addPendingText(trees, bp - 1);

                    trees.add(html());

                    if (phase == Phase.PREAMBLE || phase == Phase.POSTAMBLE) {

                        break; // Ignore newlines after html tags, in the meta content

                    }

                    if (textStart == -1) {

                        textStart = bp;

                        lastNonWhite = -1;

                    }

                    break;

                case '>':

                    newline = false;

                    addPendingText(trees, bp - 1);

                    trees.add(m.at(bp).newErroneousTree(newString(bp, bp + 1), diagSource, "dc.bad.gt"));

                    nextChar();

                    if (textStart == -1) {

                        textStart = bp;

                        lastNonWhite = -1;

                    }

                    break;

                case '{':

                    inlineTag(trees);

                    break;

                case '@':

                    if (newline) {

                        addPendingText(trees, lastNonWhite);

                        break loop;

                    }

                    // fallthrough

                default:

                    newline = false;

                    if (textStart == -1)

                        textStart = bp;

                    lastNonWhite = bp;

                    nextChar();

            }

        }

        if (lastNonWhite != -1)

            addPendingText(trees, lastNonWhite);

        return trees.toList();

    }

    /**

     * Read a series of block tags, including their content.

     * Standard tags parse their content appropriately.

     * Non-standard tags are represented by {@link UnknownBlockTag}.

     */

    protected List<DCTree> blockTags() {

        ListBuffer<DCTree> tags = new ListBuffer<>();

        while (ch == '@')

            tags.add(blockTag());

        return tags.toList();

    }

    /**

     * Read a single block tag, including its content.

     * Standard tags parse their content appropriately.

     * Non-standard tags are represented by {@link UnknownBlockTag}.

     */

    protected DCTree blockTag() {

        int p = bp;

        try {

            nextChar();

            if (isIdentifierStart(ch)) {

                Name name = readTagName();

                TagParser tp = tagParsers.get(name);

                if (tp == null) {

                    List<DCTree> content = blockContent();

                    return m.at(p).newUnknownBlockTagTree(name, content);

                } else {

                    switch (tp.getKind()) {

                        case BLOCK:

                            return tp.parse(p);

                        case INLINE:

                            return erroneous("dc.bad.inline.tag", p);

                    }

                }

            }

            blockContent();

            return erroneous("dc.no.tag.name", p);

        } catch (ParseException e) {

            blockContent();

            return erroneous(e.getMessage(), p);

        }

    }

    protected void inlineTag(ListBuffer<DCTree> list) {

        newline = false;

        nextChar();

        if (ch == '@') {

            addPendingText(list, bp - 2);

            list.add(inlineTag());

            textStart = bp;

            lastNonWhite = -1;

        } else {

            if (textStart == -1)

                textStart = bp - 1;

            lastNonWhite = bp;

        }

    }

    /**

     * Read a single inline tag, including its content.

     * Standard tags parse their content appropriately.

     * Non-standard tags are represented by {@link UnknownBlockTag}.

     * Malformed tags may be returned as {@link Erroneous}.

     */

    protected DCTree inlineTag() {

        int p = bp - 1;

        try {

            nextChar();

            if (isIdentifierStart(ch)) {

                Name name = readTagName();

                TagParser tp = tagParsers.get(name);

                if (tp == null) {

                    skipWhitespace();

                    DCTree text = inlineText(WhitespaceRetentionPolicy.REMOVE_ALL);

                    if (text != null) {

                        nextChar();

                        return m.at(p).newUnknownInlineTagTree(name, List.of(text)).setEndPos(bp);

                    }

                } else {

                    if (!tp.retainWhiteSpace) {

                        skipWhitespace();

                    }

                    if (tp.getKind() == TagParser.Kind.INLINE) {

                        DCEndPosTree<?> tree = (DCEndPosTree<?>) tp.parse(p);

                        if (tree != null) {

                            return tree.setEndPos(bp);

                        }

                    } else { // handle block tags (ex: @see) in inline content

                        inlineText(WhitespaceRetentionPolicy.REMOVE_ALL); // skip content

                        nextChar();

                    }

                }

            }

            return erroneous("dc.no.tag.name", p);

        } catch (ParseException e) {

            return erroneous(e.getMessage(), p);

        }

    }

    private static enum WhitespaceRetentionPolicy {

        RETAIN_ALL,

        REMOVE_FIRST_SPACE,

        REMOVE_ALL

    }

    /**

     * Read plain text content of an inline tag.

     * Matching pairs of { } are skipped; the text is terminated by the first

     * unmatched }. It is an error if the beginning of the next tag is detected.

     */

    private DCTree inlineText(WhitespaceRetentionPolicy whitespacePolicy) throws ParseException {

        switch (whitespacePolicy) {

            case REMOVE_ALL:

                skipWhitespace();

                break;

            case REMOVE_FIRST_SPACE:

                if (ch == ' ')

                    nextChar();

                break;

            case RETAIN_ALL:

            default:

                // do nothing

                break;

        }

        int pos = bp;

        int depth = 1;

        loop:

        while (bp < buflen) {

            switch (ch) {

                case '\n': case '\r': case '\f':

                    newline = true;

                    break;

                case ' ': case '\t':

                    break;

                case '{':

                    newline = false;

                    lastNonWhite = bp;

                    depth++;

                    break;

                case '}':

                    if (--depth == 0) {

                        return m.at(pos).newTextTree(newString(pos, bp));

                    }

                    newline = false;

                    lastNonWhite = bp;

                    break;

                case '@':

                    if (newline)

                        break loop;

                    newline = false;

                    lastNonWhite = bp;

                    break;

                default:

                    newline = false;

                    lastNonWhite = bp;

                    break;

            }

            nextChar();

        }

        throw new ParseException("dc.unterminated.inline.tag");

    }

    /**

     * Read Java class name, possibly followed by member

     * Matching pairs of {@literal < >} are skipped. The text is terminated by the first

     * unmatched }. It is an error if the beginning of the next tag is detected.

     */

    // TODO: boolean allowMember should be enum FORBID, ALLOW, REQUIRE

    // TODO: improve quality of parse to forbid bad constructions.

    // TODO: update to use ReferenceParser

    @SuppressWarnings("fallthrough")

    protected DCReference reference(boolean allowMember) throws ParseException {

        int pos = bp;

        int depth = 0;

        // scan to find the end of the signature, by looking for the first

        // whitespace not enclosed in () or <>, or the end of the tag

        loop:

        while (bp < buflen) {

            switch (ch) {

                case '\n': case '\r': case '\f':

                    newline = true;

                    // fallthrough

                case ' ': case '\t':

                    if (depth == 0)

                        break loop;

                    break;

                case '(':

                case '<':

                    newline = false;

                    depth++;

                    break;

                case ')':

                case '>':

                    newline = false;

                    --depth;

                    break;

                case '}':

                    if (bp == pos)

                        return null;

                    newline = false;

                    break loop;

                case '@':

                    if (newline)

                        break loop;

                    // fallthrough

                default:

                    newline = false;

            }

            nextChar();

        }

        if (depth != 0)

            throw new ParseException("dc.unterminated.signature");

        String sig = newString(pos, bp);

        // Break sig apart into qualifiedExpr member paramTypes.

        JCTree qualExpr;

        Name member;

        List<JCTree> paramTypes;

        Log.DeferredDiagnosticHandler deferredDiagnosticHandler

                = new Log.DeferredDiagnosticHandler(fac.log);

        try {

            int hash = sig.indexOf("#");

            int lparen = sig.indexOf("(", hash + 1);

            if (hash == -1) {

                if (lparen == -1) {

                    qualExpr = parseType(sig);

                    member = null;

                } else {

                    qualExpr = null;

                    member = parseMember(sig.substring(0, lparen));

                }

            } else {

                qualExpr = (hash == 0) ? null : parseType(sig.substring(0, hash));

                if (lparen == -1)