1 /*

     2  * Copyright (c) 2004, 2010, 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 

    26 package com.sun.tools.javac.parser;

    27 

    28 import java.nio.*;

    29 

    30 import com.sun.tools.javac.util.*;

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

    32 

    33 /** An extension to the base lexical analyzer that captures

    34  *  and processes the contents of doc comments.  It does so by

    35  *  translating Unicode escape sequences and by stripping the

    36  *  leading whitespace and starts from each line of the comment.

    37  *

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

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

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

    41  *  deletion without notice.</b>

    42  */

    43 public class DocCommentScanner extends Scanner {

    44 

    45     /** Create a scanner from the input buffer.  buffer must implement

    46      *  array() and compact(), and remaining() must be less than limit().

    47      */

    48     protected DocCommentScanner(ScannerFactory fac, CharBuffer buffer) {

    49         super(fac, buffer);

    50     }

    51 

    52     /** Create a scanner from the input array.  The array must have at

    53      *  least a single character of extra space.

    54      */

    55     protected DocCommentScanner(ScannerFactory fac, char[] input, int inputLength) {

    56         super(fac, input, inputLength);

    57     }

    58 

    59     /** Starting position of the comment in original source

    60      */

    61     private int pos;

    62 

    63     /** The comment input buffer, index of next chacter to be read,

    64      *  index of one past last character in buffer.

    65      */

    66     private char[] buf;

    67     private int bp;

    68     private int buflen;

    69 

    70     /** The current character.

    71      */

    72     private char ch;

    73 

    74     /** The column number position of the current character.

    75      */

    76     private int col;

    77 

    78     /** The buffer index of the last converted Unicode character

    79      */

    80     private int unicodeConversionBp = 0;

    81 

    82     /**

    83      * Buffer for doc comment.

    84      */

    85     private char[] docCommentBuffer = new char[1024];

    86 

    87     /**

    88      * Number of characters in doc comment buffer.

    89      */

    90     private int docCommentCount;

    91 

    92     /**

    93      * Translated and stripped contents of doc comment

    94      */

    95     private String docComment = null;

    96 

    97 

    98     /** Unconditionally expand the comment buffer.

    99      */

   100     private void expandCommentBuffer() {

   101         char[] newBuffer = new char[docCommentBuffer.length * 2];

   102         System.arraycopy(docCommentBuffer, 0, newBuffer,

   103                          0, docCommentBuffer.length);

   104         docCommentBuffer = newBuffer;

   105     }

   106 

   107     /** Convert an ASCII digit from its base (8, 10, or 16)

   108      *  to its value.

   109      */

   110     private int digit(int base) {

   111         char c = ch;

   112         int result = Character.digit(c, base);

   113         if (result >= 0 && c > 0x7f) {

   114             ch = "0123456789abcdef".charAt(result);

   115         }

   116         return result;

   117     }

   118 

   119     /** Convert Unicode escape; bp points to initial '\' character

   120      *  (Spec 3.3).

   121      */

   122     private void convertUnicode() {

   123         if (ch == '\\' && unicodeConversionBp != bp) {

   124             bp++; ch = buf[bp]; col++;

   125             if (ch == 'u') {

   126                 do {

   127                     bp++; ch = buf[bp]; col++;

   128                 } while (ch == 'u');

   129                 int limit = bp + 3;

   130                 if (limit < buflen) {

   131                     int d = digit(16);

   132                     int code = d;

   133                     while (bp < limit && d >= 0) {

   134                         bp++; ch = buf[bp]; col++;

   135                         d = digit(16);

   136                         code = (code << 4) + d;

   137                     }

   138                     if (d >= 0) {

   139                         ch = (char)code;

   140                         unicodeConversionBp = bp;

   141                         return;

   142                     }

   143                 }

   144                 // "illegal.Unicode.esc", reported by base scanner

   145             } else {

   146                 bp--;

   147                 ch = '\\';

   148                 col--;

   149             }

   150         }

   151     }

   152 

   153 

   154     /** Read next character.

   155      */

   156     private void scanChar() {

   157         bp++;

   158         ch = buf[bp];

   159         switch (ch) {

   160         case '\r': // return

   161             col = 0;

   162             break;

   163         case '\n': // newline

   164             if (bp == 0 || buf[bp-1] != '\r') {

   165                 col = 0;

   166             }

   167             break;

   168         case '\t': // tab

   169             col = (col / TabInc * TabInc) + TabInc;

   170             break;

   171         case '\\': // possible Unicode

   172             col++;

   173             convertUnicode();

   174             break;

   175         default:

   176             col++;

   177             break;

   178         }

   179     }

   180 

   181     /**

   182      * Read next character in doc comment, skipping over double '\' characters.

   183      * If a double '\' is skipped, put in the buffer and update buffer count.

   184      */

   185     private void scanDocCommentChar() {

   186         scanChar();

   187         if (ch == '\\') {

   188             if (buf[bp+1] == '\\' && unicodeConversionBp != bp) {

   189                 if (docCommentCount == docCommentBuffer.length)

   190                     expandCommentBuffer();

   191                 docCommentBuffer[docCommentCount++] = ch;

   192                 bp++; col++;

   193             } else {

   194                 convertUnicode();

   195             }

   196         }

   197     }

   198 

   199     /* Reset doc comment before reading each new token

   200      */

   201     public void nextToken() {

   202         docComment = null;

   203         super.nextToken();

   204     }

   205 

   206     /**

   207      * Returns the documentation string of the current token.

   208      */

   209     public String docComment() {

   210         return docComment;

   211     }

   212 

   213     /**

   214      * Process a doc comment and make the string content available.

   215      * Strips leading whitespace and stars.

   216      */

   217     @SuppressWarnings("fallthrough")

   218     protected void processComment(CommentStyle style) {

   219         if (style != CommentStyle.JAVADOC) {

   220             return;

   221         }

   222 

   223         pos = pos();

   224         buf = getRawCharacters(pos, endPos());

   225         buflen = buf.length;

   226         bp = 0;

   227         col = 0;

   228 

   229         docCommentCount = 0;

   230 

   231         boolean firstLine = true;

   232 

   233         // Skip over first slash

   234         scanDocCommentChar();

   235         // Skip over first star

   236         scanDocCommentChar();

   237 

   238         // consume any number of stars

   239         while (bp < buflen && ch == '*') {

   240             scanDocCommentChar();

   241         }

   242         // is the comment in the form /**/, /***/, /****/, etc. ?

   243         if (bp < buflen && ch == '/') {

   244             docComment = "";

   245             return;

   246         }

   247 

   248         // skip a newline on the first line of the comment.

   249         if (bp < buflen) {

   250             if (ch == LF) {

   251                 scanDocCommentChar();

   252                 firstLine = false;

   253             } else if (ch == CR) {

   254                 scanDocCommentChar();

   255                 if (ch == LF) {

   256                     scanDocCommentChar();

   257                     firstLine = false;

   258                 }

   259             }

   260         }

   261 

   262     outerLoop:

   263 

   264         // The outerLoop processes the doc comment, looping once

   265         // for each line.  For each line, it first strips off

   266         // whitespace, then it consumes any stars, then it

   267         // puts the rest of the line into our buffer.

   268         while (bp < buflen) {

   269 

   270             // The wsLoop consumes whitespace from the beginning

   271             // of each line.

   272         wsLoop:

   273 

   274             while (bp < buflen) {

   275                 switch(ch) {

   276                 case ' ':

   277                     scanDocCommentChar();

   278                     break;

   279                 case '\t':

   280                     col = ((col - 1) / TabInc * TabInc) + TabInc;

   281                     scanDocCommentChar();

   282                     break;

   283                 case FF:

   284                     col = 0;

   285                     scanDocCommentChar();

   286                     break;

   287 // Treat newline at beginning of line (blank line, no star)

   288 // as comment text.  Old Javadoc compatibility requires this.

   289 /*---------------------------------*

   290                 case CR: // (Spec 3.4)

   291                     scanDocCommentChar();

   292                     if (ch == LF) {

   293                         col = 0;

   294                         scanDocCommentChar();

   295                     }

   296                     break;

   297                 case LF: // (Spec 3.4)

   298                     scanDocCommentChar();

   299                     break;

   300 *---------------------------------*/

   301                 default:

   302                     // we've seen something that isn't whitespace;

   303                     // jump out.

   304                     break wsLoop;

   305                 }

   306             }

   307 

   308             // Are there stars here?  If so, consume them all

   309             // and check for the end of comment.

   310             if (ch == '*') {

   311                 // skip all of the stars

   312                 do {

   313                     scanDocCommentChar();

   314                 } while (ch == '*');

   315 

   316                 // check for the closing slash.

   317                 if (ch == '/') {

   318                     // We're done with the doc comment

   319                     // scanChar() and breakout.

   320                     break outerLoop;

   321                 }

   322             } else if (! firstLine) {

   323                 //The current line does not begin with a '*' so we will indent it.

   324                 for (int i = 1; i < col; i++) {

   325                     if (docCommentCount == docCommentBuffer.length)

   326                         expandCommentBuffer();

   327                     docCommentBuffer[docCommentCount++] = ' ';

   328                 }

   329             }

   330 

   331             // The textLoop processes the rest of the characters

   332             // on the line, adding them to our buffer.

   333         textLoop:

   334             while (bp < buflen) {

   335                 switch (ch) {

   336                 case '*':

   337                     // Is this just a star?  Or is this the

   338                     // end of a comment?

   339                     scanDocCommentChar();

   340                     if (ch == '/') {

   341                         // This is the end of the comment,

   342                         // set ch and return our buffer.

   343                         break outerLoop;

   344                     }

   345                     // This is just an ordinary star.  Add it to

   346                     // the buffer.

   347                     if (docCommentCount == docCommentBuffer.length)

   348                         expandCommentBuffer();

   349                     docCommentBuffer[docCommentCount++] = '*';

   350                     break;

   351                 case ' ':

   352                 case '\t':

   353                     if (docCommentCount == docCommentBuffer.length)

   354                         expandCommentBuffer();

   355                     docCommentBuffer[docCommentCount++] = ch;

   356                     scanDocCommentChar();

   357                     break;

   358                 case FF:

   359                     scanDocCommentChar();

   360                     break textLoop; // treat as end of line

   361                 case CR: // (Spec 3.4)

   362                     scanDocCommentChar();

   363                     if (ch != LF) {

   364                         // Canonicalize CR-only line terminator to LF

   365                         if (docCommentCount == docCommentBuffer.length)

   366                             expandCommentBuffer();

   367                         docCommentBuffer[docCommentCount++] = (char)LF;

   368                         break textLoop;

   369                     }

   370                     /* fall through to LF case */

   371                 case LF: // (Spec 3.4)

   372                     // We've seen a newline.  Add it to our

   373                     // buffer and break out of this loop,

   374                     // starting fresh on a new line.

   375                     if (docCommentCount == docCommentBuffer.length)

   376                         expandCommentBuffer();

   377                     docCommentBuffer[docCommentCount++] = ch;

   378                     scanDocCommentChar();

   379                     break textLoop;

   380                 default:

   381                     // Add the character to our buffer.

   382                     if (docCommentCount == docCommentBuffer.length)

   383                         expandCommentBuffer();

   384                     docCommentBuffer[docCommentCount++] = ch;

   385                     scanDocCommentChar();

   386                 }

   387             } // end textLoop

   388             firstLine = false;

   389         } // end outerLoop

   390 

   391         if (docCommentCount > 0) {

   392             int i = docCommentCount - 1;

   393         trailLoop:

   394             while (i > -1) {

   395                 switch (docCommentBuffer[i]) {

   396                 case '*':

   397                     i--;

   398                     break;

   399                 default:

   400                     break trailLoop;

   401                 }

   402             }

   403             docCommentCount = i + 1;

   404 

   405             // Store the text of the doc comment

   406             docComment = new String(docCommentBuffer, 0 , docCommentCount);

   407         } else {

   408             docComment = "";

   409         }

   410     }

   411 

   412     /** Build a map for translating between line numbers and

   413      * positions in the input.

   414      *

   415      * @return a LineMap */

   416     public Position.LineMap getLineMap() {

   417         char[] buf = getRawCharacters();

   418         return Position.makeLineMap(buf, buf.length, true);

   419     }

   420 }