1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/src/share/classes/com/sun/tools/javac/parser/DocCommentScanner.java Sat Dec 01 00:00:00 2007 +0000
1.3 @@ -0,0 +1,454 @@
1.4 +/*
1.5 + * Copyright 2004-2006 Sun Microsystems, Inc. All Rights Reserved.
1.6 + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
1.7 + *
1.8 + * This code is free software; you can redistribute it and/or modify it
1.9 + * under the terms of the GNU General Public License version 2 only, as
1.10 + * published by the Free Software Foundation. Sun designates this
1.11 + * particular file as subject to the "Classpath" exception as provided
1.12 + * by Sun in the LICENSE file that accompanied this code.
1.13 + *
1.14 + * This code is distributed in the hope that it will be useful, but WITHOUT
1.15 + * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
1.16 + * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
1.17 + * version 2 for more details (a copy is included in the LICENSE file that
1.18 + * accompanied this code).
1.19 + *
1.20 + * You should have received a copy of the GNU General Public License version
1.21 + * 2 along with this work; if not, write to the Free Software Foundation,
1.22 + * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
1.23 + *
1.24 + * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
1.25 + * CA 95054 USA or visit www.sun.com if you need additional information or
1.26 + * have any questions.
1.27 + */
1.28 +
1.29 +package com.sun.tools.javac.parser;
1.30 +
1.31 +import java.io.*;
1.32 +import java.nio.*;
1.33 +
1.34 +import com.sun.tools.javac.util.*;
1.35 +import static com.sun.tools.javac.util.LayoutCharacters.*;
1.36 +
1.37 +/** An extension to the base lexical analyzer that captures
1.38 + * and processes the contents of doc comments. It does so by
1.39 + * translating Unicode escape sequences and by stripping the
1.40 + * leading whitespace and starts from each line of the comment.
1.41 + *
1.42 + * <p><b>This is NOT part of any API supported by Sun Microsystems. If
1.43 + * you write code that depends on this, you do so at your own risk.
1.44 + * This code and its internal interfaces are subject to change or
1.45 + * deletion without notice.</b>
1.46 + */
1.47 +public class DocCommentScanner extends Scanner {
1.48 +
1.49 + /** A factory for creating scanners. */
1.50 + public static class Factory extends Scanner.Factory {
1.51 +
1.52 + public static void preRegister(final Context context) {
1.53 + context.put(scannerFactoryKey, new Context.Factory<Scanner.Factory>() {
1.54 + public Factory make() {
1.55 + return new Factory(context);
1.56 + }
1.57 + });
1.58 + }
1.59 +
1.60 + /** Create a new scanner factory. */
1.61 + protected Factory(Context context) {
1.62 + super(context);
1.63 + }
1.64 +
1.65 + @Override
1.66 + public Scanner newScanner(CharSequence input) {
1.67 + if (input instanceof CharBuffer) {
1.68 + return new DocCommentScanner(this, (CharBuffer)input);
1.69 + } else {
1.70 + char[] array = input.toString().toCharArray();
1.71 + return newScanner(array, array.length);
1.72 + }
1.73 + }
1.74 +
1.75 + @Override
1.76 + public Scanner newScanner(char[] input, int inputLength) {
1.77 + return new DocCommentScanner(this, input, inputLength);
1.78 + }
1.79 + }
1.80 +
1.81 +
1.82 + /** Create a scanner from the input buffer. buffer must implement
1.83 + * array() and compact(), and remaining() must be less than limit().
1.84 + */
1.85 + protected DocCommentScanner(Factory fac, CharBuffer buffer) {
1.86 + super(fac, buffer);
1.87 + }
1.88 +
1.89 + /** Create a scanner from the input array. The array must have at
1.90 + * least a single character of extra space.
1.91 + */
1.92 + protected DocCommentScanner(Factory fac, char[] input, int inputLength) {
1.93 + super(fac, input, inputLength);
1.94 + }
1.95 +
1.96 + /** Starting position of the comment in original source
1.97 + */
1.98 + private int pos;
1.99 +
1.100 + /** The comment input buffer, index of next chacter to be read,
1.101 + * index of one past last character in buffer.
1.102 + */
1.103 + private char[] buf;
1.104 + private int bp;
1.105 + private int buflen;
1.106 +
1.107 + /** The current character.
1.108 + */
1.109 + private char ch;
1.110 +
1.111 + /** The column number position of the current character.
1.112 + */
1.113 + private int col;
1.114 +
1.115 + /** The buffer index of the last converted Unicode character
1.116 + */
1.117 + private int unicodeConversionBp = 0;
1.118 +
1.119 + /**
1.120 + * Buffer for doc comment.
1.121 + */
1.122 + private char[] docCommentBuffer = new char[1024];
1.123 +
1.124 + /**
1.125 + * Number of characters in doc comment buffer.
1.126 + */
1.127 + private int docCommentCount;
1.128 +
1.129 + /**
1.130 + * Translated and stripped contents of doc comment
1.131 + */
1.132 + private String docComment = null;
1.133 +
1.134 +
1.135 + /** Unconditionally expand the comment buffer.
1.136 + */
1.137 + private void expandCommentBuffer() {
1.138 + char[] newBuffer = new char[docCommentBuffer.length * 2];
1.139 + System.arraycopy(docCommentBuffer, 0, newBuffer,
1.140 + 0, docCommentBuffer.length);
1.141 + docCommentBuffer = newBuffer;
1.142 + }
1.143 +
1.144 + /** Convert an ASCII digit from its base (8, 10, or 16)
1.145 + * to its value.
1.146 + */
1.147 + private int digit(int base) {
1.148 + char c = ch;
1.149 + int result = Character.digit(c, base);
1.150 + if (result >= 0 && c > 0x7f) {
1.151 + ch = "0123456789abcdef".charAt(result);
1.152 + }
1.153 + return result;
1.154 + }
1.155 +
1.156 + /** Convert Unicode escape; bp points to initial '\' character
1.157 + * (Spec 3.3).
1.158 + */
1.159 + private void convertUnicode() {
1.160 + if (ch == '\\' && unicodeConversionBp != bp) {
1.161 + bp++; ch = buf[bp]; col++;
1.162 + if (ch == 'u') {
1.163 + do {
1.164 + bp++; ch = buf[bp]; col++;
1.165 + } while (ch == 'u');
1.166 + int limit = bp + 3;
1.167 + if (limit < buflen) {
1.168 + int d = digit(16);
1.169 + int code = d;
1.170 + while (bp < limit && d >= 0) {
1.171 + bp++; ch = buf[bp]; col++;
1.172 + d = digit(16);
1.173 + code = (code << 4) + d;
1.174 + }
1.175 + if (d >= 0) {
1.176 + ch = (char)code;
1.177 + unicodeConversionBp = bp;
1.178 + return;
1.179 + }
1.180 + }
1.181 + // "illegal.Unicode.esc", reported by base scanner
1.182 + } else {
1.183 + bp--;
1.184 + ch = '\\';
1.185 + col--;
1.186 + }
1.187 + }
1.188 + }
1.189 +
1.190 +
1.191 + /** Read next character.
1.192 + */
1.193 + private void scanChar() {
1.194 + bp++;
1.195 + ch = buf[bp];
1.196 + switch (ch) {
1.197 + case '\r': // return
1.198 + col = 0;
1.199 + break;
1.200 + case '\n': // newline
1.201 + if (bp == 0 || buf[bp-1] != '\r') {
1.202 + col = 0;
1.203 + }
1.204 + break;
1.205 + case '\t': // tab
1.206 + col = (col / TabInc * TabInc) + TabInc;
1.207 + break;
1.208 + case '\\': // possible Unicode
1.209 + col++;
1.210 + convertUnicode();
1.211 + break;
1.212 + default:
1.213 + col++;
1.214 + break;
1.215 + }
1.216 + }
1.217 +
1.218 + /**
1.219 + * Read next character in doc comment, skipping over double '\' characters.
1.220 + * If a double '\' is skipped, put in the buffer and update buffer count.
1.221 + */
1.222 + private void scanDocCommentChar() {
1.223 + scanChar();
1.224 + if (ch == '\\') {
1.225 + if (buf[bp+1] == '\\' && unicodeConversionBp != bp) {
1.226 + if (docCommentCount == docCommentBuffer.length)
1.227 + expandCommentBuffer();
1.228 + docCommentBuffer[docCommentCount++] = ch;
1.229 + bp++; col++;
1.230 + } else {
1.231 + convertUnicode();
1.232 + }
1.233 + }
1.234 + }
1.235 +
1.236 + /* Reset doc comment before reading each new token
1.237 + */
1.238 + public void nextToken() {
1.239 + docComment = null;
1.240 + super.nextToken();
1.241 + }
1.242 +
1.243 + /**
1.244 + * Returns the documentation string of the current token.
1.245 + */
1.246 + public String docComment() {
1.247 + return docComment;
1.248 + }
1.249 +
1.250 + /**
1.251 + * Process a doc comment and make the string content available.
1.252 + * Strips leading whitespace and stars.
1.253 + */
1.254 + @SuppressWarnings("fallthrough")
1.255 + protected void processComment(CommentStyle style) {
1.256 + if (style != CommentStyle.JAVADOC) {
1.257 + return;
1.258 + }
1.259 +
1.260 + pos = pos();
1.261 + buf = getRawCharacters(pos, endPos());
1.262 + buflen = buf.length;
1.263 + bp = 0;
1.264 + col = 0;
1.265 +
1.266 + docCommentCount = 0;
1.267 +
1.268 + boolean firstLine = true;
1.269 +
1.270 + // Skip over first slash
1.271 + scanDocCommentChar();
1.272 + // Skip over first star
1.273 + scanDocCommentChar();
1.274 +
1.275 + // consume any number of stars
1.276 + while (bp < buflen && ch == '*') {
1.277 + scanDocCommentChar();
1.278 + }
1.279 + // is the comment in the form /**/, /***/, /****/, etc. ?
1.280 + if (bp < buflen && ch == '/') {
1.281 + docComment = "";
1.282 + return;
1.283 + }
1.284 +
1.285 + // skip a newline on the first line of the comment.
1.286 + if (bp < buflen) {
1.287 + if (ch == LF) {
1.288 + scanDocCommentChar();
1.289 + firstLine = false;
1.290 + } else if (ch == CR) {
1.291 + scanDocCommentChar();
1.292 + if (ch == LF) {
1.293 + scanDocCommentChar();
1.294 + firstLine = false;
1.295 + }
1.296 + }
1.297 + }
1.298 +
1.299 + outerLoop:
1.300 +
1.301 + // The outerLoop processes the doc comment, looping once
1.302 + // for each line. For each line, it first strips off
1.303 + // whitespace, then it consumes any stars, then it
1.304 + // puts the rest of the line into our buffer.
1.305 + while (bp < buflen) {
1.306 +
1.307 + // The wsLoop consumes whitespace from the beginning
1.308 + // of each line.
1.309 + wsLoop:
1.310 +
1.311 + while (bp < buflen) {
1.312 + switch(ch) {
1.313 + case ' ':
1.314 + scanDocCommentChar();
1.315 + break;
1.316 + case '\t':
1.317 + col = ((col - 1) / TabInc * TabInc) + TabInc;
1.318 + scanDocCommentChar();
1.319 + break;
1.320 + case FF:
1.321 + col = 0;
1.322 + scanDocCommentChar();
1.323 + break;
1.324 +// Treat newline at beginning of line (blank line, no star)
1.325 +// as comment text. Old Javadoc compatibility requires this.
1.326 +/*---------------------------------*
1.327 + case CR: // (Spec 3.4)
1.328 + scanDocCommentChar();
1.329 + if (ch == LF) {
1.330 + col = 0;
1.331 + scanDocCommentChar();
1.332 + }
1.333 + break;
1.334 + case LF: // (Spec 3.4)
1.335 + scanDocCommentChar();
1.336 + break;
1.337 +*---------------------------------*/
1.338 + default:
1.339 + // we've seen something that isn't whitespace;
1.340 + // jump out.
1.341 + break wsLoop;
1.342 + }
1.343 + }
1.344 +
1.345 + // Are there stars here? If so, consume them all
1.346 + // and check for the end of comment.
1.347 + if (ch == '*') {
1.348 + // skip all of the stars
1.349 + do {
1.350 + scanDocCommentChar();
1.351 + } while (ch == '*');
1.352 +
1.353 + // check for the closing slash.
1.354 + if (ch == '/') {
1.355 + // We're done with the doc comment
1.356 + // scanChar() and breakout.
1.357 + break outerLoop;
1.358 + }
1.359 + } else if (! firstLine) {
1.360 + //The current line does not begin with a '*' so we will indent it.
1.361 + for (int i = 1; i < col; i++) {
1.362 + if (docCommentCount == docCommentBuffer.length)
1.363 + expandCommentBuffer();
1.364 + docCommentBuffer[docCommentCount++] = ' ';
1.365 + }
1.366 + }
1.367 +
1.368 + // The textLoop processes the rest of the characters
1.369 + // on the line, adding them to our buffer.
1.370 + textLoop:
1.371 + while (bp < buflen) {
1.372 + switch (ch) {
1.373 + case '*':
1.374 + // Is this just a star? Or is this the
1.375 + // end of a comment?
1.376 + scanDocCommentChar();
1.377 + if (ch == '/') {
1.378 + // This is the end of the comment,
1.379 + // set ch and return our buffer.
1.380 + break outerLoop;
1.381 + }
1.382 + // This is just an ordinary star. Add it to
1.383 + // the buffer.
1.384 + if (docCommentCount == docCommentBuffer.length)
1.385 + expandCommentBuffer();
1.386 + docCommentBuffer[docCommentCount++] = '*';
1.387 + break;
1.388 + case ' ':
1.389 + case '\t':
1.390 + if (docCommentCount == docCommentBuffer.length)
1.391 + expandCommentBuffer();
1.392 + docCommentBuffer[docCommentCount++] = ch;
1.393 + scanDocCommentChar();
1.394 + break;
1.395 + case FF:
1.396 + scanDocCommentChar();
1.397 + break textLoop; // treat as end of line
1.398 + case CR: // (Spec 3.4)
1.399 + scanDocCommentChar();
1.400 + if (ch != LF) {
1.401 + // Canonicalize CR-only line terminator to LF
1.402 + if (docCommentCount == docCommentBuffer.length)
1.403 + expandCommentBuffer();
1.404 + docCommentBuffer[docCommentCount++] = (char)LF;
1.405 + break textLoop;
1.406 + }
1.407 + /* fall through to LF case */
1.408 + case LF: // (Spec 3.4)
1.409 + // We've seen a newline. Add it to our
1.410 + // buffer and break out of this loop,
1.411 + // starting fresh on a new line.
1.412 + if (docCommentCount == docCommentBuffer.length)
1.413 + expandCommentBuffer();
1.414 + docCommentBuffer[docCommentCount++] = ch;
1.415 + scanDocCommentChar();
1.416 + break textLoop;
1.417 + default:
1.418 + // Add the character to our buffer.
1.419 + if (docCommentCount == docCommentBuffer.length)
1.420 + expandCommentBuffer();
1.421 + docCommentBuffer[docCommentCount++] = ch;
1.422 + scanDocCommentChar();
1.423 + }
1.424 + } // end textLoop
1.425 + firstLine = false;
1.426 + } // end outerLoop
1.427 +
1.428 + if (docCommentCount > 0) {
1.429 + int i = docCommentCount - 1;
1.430 + trailLoop:
1.431 + while (i > -1) {
1.432 + switch (docCommentBuffer[i]) {
1.433 + case '*':
1.434 + i--;
1.435 + break;
1.436 + default:
1.437 + break trailLoop;
1.438 + }
1.439 + }
1.440 + docCommentCount = i + 1;
1.441 +
1.442 + // Store the text of the doc comment
1.443 + docComment = new String(docCommentBuffer, 0 , docCommentCount);
1.444 + } else {
1.445 + docComment = "";
1.446 + }
1.447 + }
1.448 +
1.449 + /** Build a map for translating between line numbers and
1.450 + * positions in the input.
1.451 + *
1.452 + * @return a LineMap */
1.453 + public Position.LineMap getLineMap() {
1.454 + char[] buf = getRawCharacters();
1.455 + return Position.makeLineMap(buf, buf.length, true);
1.456 + }
1.457 +}
