build/tools/droiddoc/src/LinkReference.java

   1 /*
   2  * Copyright (C) 2008 The Android Open Source Project
   3  *
   4  * Licensed under the Apache License, Version 2.0 (the "License");
   5  * you may not use this file except in compliance with the License.
   6  * You may obtain a copy of the License at
   7  *
   8  *      http://www.apache.org/licenses/LICENSE-2.0
   9  *
  10  * Unless required by applicable law or agreed to in writing, software
  11  * distributed under the License is distributed on an "AS IS" BASIS,
  12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  13  * See the License for the specific language governing permissions and
  14  * limitations under the License.
  15  */
  16
  17 import java.util.regex.Pattern;
  18 import java.util.regex.Matcher;
  19 import java.util.ArrayList;
  20
  21 /**
  22  * Class that represents what you see in an link or see tag.  This is
  23  * factored out of SeeTagInfo so it can be used elsewhere (like AttrTagInfo).
  24  */
  25 public class LinkReference {
  26
  27     /** The original text. */
  28     public String text;
  29
  30     /** The kind of this tag, if we have a new suggestion after parsing. */
  31     public String kind;
  32
  33     /** The user visible text. */
  34     public String label;
  35
  36     /** The link. */
  37     public String href;
  38
  39     /** The {@link PackageInfo} if any. */
  40     public PackageInfo packageInfo;
  41
  42     /** The {@link ClassInfo} if any. */
  43     public ClassInfo classInfo;
  44
  45     /** The {@link MemberInfo} if any. */
  46     public MemberInfo memberInfo;
  47
  48     /** The name of the referenced member PackageInfo} if any. */
  49     public String referencedMemberName;
  50
  51     /** Set to true if everything is a-ok */
  52     public boolean good;
  53
  54     /**
  55      * regex pattern to use when matching explicit "<a href" reference text
  56      */
  57     private static final Pattern HREF_PATTERN
  58             = Pattern.compile("^<a href=\"([^\"]*)\">([^<]*)</a>[ \n\r\t]*$",
  59                               Pattern.CASE_INSENSITIVE);
  60
  61     /**
  62      * regex pattern to use when matching double-quoted reference text
  63      */
  64     private static final Pattern QUOTE_PATTERN
  65             = Pattern.compile("^\"([^\"]*)\"[ \n\r\t]*$");
  66
  67     /**
  68      * Parse and resolve a link string.
  69      *
  70      * @param text the original text
  71      * @param base the class or whatever that this link is on
  72      * @param pos the original position in the source document
  73      * @return a new link reference.  It always returns something.  If there was an
  74      *         error, it logs it and fills in href and label with error text.
  75      */
  76     public static LinkReference parse(String text, ContainerInfo base, SourcePositionInfo pos,
  77                                         boolean printOnErrors) {
  78         LinkReference result = new LinkReference();
  79         result.text = text;
  80
  81         int index;
  82         int len = text.length();
  83         int pairs = 0;
  84         int pound = -1;
  85         // split the string
  86         done: {
  87             for (index=0; index<len; index++) {
  88                 char c = text.charAt(index);
  89                 switch (c)
  90                 {
  91                     case '(':
  92                         pairs++;
  93                         break;
  94                     case '[':
  95                         pairs++;
  96                         break;
  97                     case ')':
  98                         pairs--;
  99                         break;
 100                     case ']':
 101                         pairs--;
 102                         break;
 103                     case ' ':
 104                     case '\t':
 105                     case '\r':
 106                     case '\n':
 107                         if (pairs == 0) {
 108                             break done;
 109                         }
 110                         break;
 111                     case '#':
 112                         if (pound < 0) {
 113                             pound = index;
 114                         }
 115                         break;
 116                 }
 117             }
 118         }
 119         if (index == len && pairs != 0) {
 120             Errors.error(Errors.UNRESOLVED_LINK, pos,
 121                         "unable to parse link/see tag: " + text.trim());
 122             return result;
 123         }
 124
 125         int linkend = index;
 126
 127         for (; index<len; index++) {
 128             char c = text.charAt(index);
 129             if (!(c == ' ' || c == '\t' || c == '\r' || c == '\n')) {
 130                 break;
 131             }
 132         }
 133
 134         result.label = text.substring(index);
 135
 136         String ref;
 137         String mem;
 138         if (pound == 0) {
 139             ref = null;
 140             mem = text.substring(1, linkend);
 141         }
 142         else if (pound > 0) {
 143             ref = text.substring(0, pound);
 144             mem = text.substring(pound+1, linkend);
 145         }
 146         else {
 147             ref = text.substring(0, linkend);
 148             mem = null;
 149         }
 150
 151         // parse parameters, if any
 152         String[] params = null;
 153         String[] paramDimensions = null;
 154         if (mem != null) {
 155             index = mem.indexOf('(');
 156             if (index > 0) {
 157                 ArrayList<String> paramList = new ArrayList<String>();
 158                 ArrayList<String> paramDimensionList = new ArrayList<String>();
 159                 len = mem.length();
 160                 int start = index+1;
 161                 final int START = 0;
 162                 final int TYPE = 1;
 163                 final int NAME = 2;
 164                 int dimension = 0;
 165                 int arraypair = 0;
 166                 int state = START;
 167                 int typestart = 0;
 168                 int typeend = -1;
 169                 for (int i=start; i<len; i++) {
 170                     char c = mem.charAt(i);
 171                     switch (state)
 172                     {
 173                         case START:
 174                             if (c!=' ' && c!='\t' && c!='\r' && c!='\n') {
 175                                 state = TYPE;
 176                                 typestart = i;
 177                             }
 178                             break;
 179                         case TYPE:
 180                             if (c == '[') {
 181                                 if (typeend < 0) {
 182                                     typeend = i;
 183                                 }
 184                                 dimension++;
 185                                 arraypair++;
 186                             }
 187                             else if (c == ']') {
 188                                 arraypair--;
 189                             }
 190                             else if (c==' ' || c=='\t' || c=='\r' || c=='\n') {
 191                                 if (typeend < 0) {
 192                                     typeend = i;
 193                                 }
 194                             }
 195                             else {
 196                                 if (typeend >= 0 || c == ')' || c == ',') {
 197                                     if (typeend < 0) {
 198                                         typeend = i;
 199                                     }
 200                                     String s = mem.substring(typestart, typeend);
 201                                     paramList.add(s);
 202                                     s = "";
 203                                     for (int j=0; j<dimension; j++) {
 204                                         s += "[]";
 205                                     }
 206                                     paramDimensionList.add(s);
 207                                     state = START;
 208                                     typeend = -1;
 209                                     dimension = 0;
 210                                     if (c == ',' || c == ')') {
 211                                         state = START;
 212                                     } else {
 213                                         state = NAME;
 214                                     }
 215                                 }
 216                             }
 217                             break;
 218                         case NAME:
 219                             if (c == ',' || c == ')') {
 220                                 state = START;
 221                             }
 222                             break;
 223                     }
 224
 225                 }
 226                 params = paramList.toArray(new String[paramList.size()]);
 227                 paramDimensions = paramDimensionList.toArray(new String[paramList.size()]);
 228                 mem = mem.substring(0, index);
 229             }
 230         }
 231
 232         ClassInfo cl = null;
 233         if (base instanceof ClassInfo) {
 234             cl = (ClassInfo)base;
 235         }
 236
 237         if (ref == null) {
 238             // no class or package was provided, assume it's this class
 239             if (cl != null) {
 240                 result.classInfo = cl;
 241             }
 242         } else {
 243             // they provided something, maybe it's a class or a package
 244             if (cl != null) {
 245                 result.classInfo = cl.extendedFindClass(ref);
 246                 if (result.classInfo == null) {
 247                     result.classInfo = cl.findClass(ref);
 248                 }
 249                 if (result.classInfo == null) {
 250                     result.classInfo = cl.findInnerClass(ref);
 251                 }
 252             }
 253             if (result.classInfo == null) {
 254                 result.classInfo = Converter.obtainClass(ref);
 255             }
 256             if (result.classInfo == null) {
 257                 result.packageInfo = Converter.obtainPackage(ref);
 258             }
 259         }
 260
 261         if (result.classInfo != null && mem != null) {
 262             // it's either a field or a method, prefer a field
 263             if (params == null) {
 264                 FieldInfo field = result.classInfo.findField(mem);
 265                 // findField looks in containing classes, so it might actually
 266                 // be somewhere else; link to where it really is, not what they
 267                 // typed.
 268                 if (field != null) {
 269                     result.classInfo = field.containingClass();
 270                     result.memberInfo = field;
 271                 }
 272             }
 273             if (result.memberInfo == null) {
 274                 MethodInfo method = result.classInfo.findMethod(mem, params, paramDimensions);
 275                 if (method != null) {
 276                     result.classInfo = method.containingClass();
 277                     result.memberInfo = method;
 278                 }
 279             }
 280         }
 281
 282         result.referencedMemberName = mem;
 283         if (params != null) {
 284             result.referencedMemberName = result.referencedMemberName + '(';
 285             len = params.length;
 286             if (len > 0) {
 287                 len--;
 288                 for (int i=0; i<len; i++) {
 289                     result.referencedMemberName = result.referencedMemberName + params[i]
 290                             + paramDimensions[i] + ", ";
 291                 }
 292                 result.referencedMemberName = result.referencedMemberName + params[len]
 293                         + paramDimensions[len];
 294             }
 295             result.referencedMemberName = result.referencedMemberName + ")";
 296         }
 297
 298         // debugging spew
 299         if (false) {
 300             result.label = result.label + "/" + ref + "/" + mem + '/';
 301             if (params != null) {
 302                 for (int i=0; i<params.length; i++) {
 303                     result.label += params[i] + "|";
 304                 }
 305             }
 306
 307             FieldInfo f = (result.memberInfo instanceof FieldInfo)
 308                         ? (FieldInfo)result.memberInfo
 309                         : null;
 310             MethodInfo m = (result.memberInfo instanceof MethodInfo)
 311                         ? (MethodInfo)result.memberInfo
 312                         : null;
 313             result.label = result.label
 314                         + "/package=" + (result.packageInfo!=null?result.packageInfo.name():"")
 315                         + "/class=" + (result.classInfo!=null?result.classInfo.qualifiedName():"")
 316                         + "/field=" + (f!=null?f.name():"")
 317                         + "/method=" + (m!=null?m.name():"");
 318
 319         }
 320
 321         MethodInfo method = null;
 322         boolean skipHref = false;
 323
 324         if (result.memberInfo != null && result.memberInfo.isExecutable()) {
 325            method = (MethodInfo)result.memberInfo;
 326         }
 327
 328         if (text.startsWith("\"")) {
 329             // literal quoted reference (e.g., a book title)
 330             Matcher matcher = QUOTE_PATTERN.matcher(text);
 331             if (! matcher.matches()) {
 332                 Errors.error(Errors.UNRESOLVED_LINK, pos,
 333                         "unbalanced quoted link/see tag: " + text.trim());
 334                 result.makeError();
 335                 return result;
 336             }
 337             skipHref = true;
 338             result.label = matcher.group(1);
 339             result.kind = "@seeJustLabel";
 340         }
 341         else if (text.startsWith("<")) {
 342             // explicit "<a href" form
 343             Matcher matcher = HREF_PATTERN.matcher(text);
 344             if (! matcher.matches()) {
 345                 Errors.error(Errors.UNRESOLVED_LINK, pos,
 346                         "invalid <a> link/see tag: " + text.trim());
 347                 result.makeError();
 348                 return result;
 349             }
 350             result.href = matcher.group(1);
 351             result.label = matcher.group(2);
 352             result.kind = "@seeHref";
 353         }
 354         else if (result.packageInfo != null) {
 355             result.href = result.packageInfo.htmlPage();
 356             if (result.label.length() == 0) {
 357                 result.href = result.packageInfo.htmlPage();
 358                 result.label = result.packageInfo.name();
 359             }
 360         }
 361         else if (result.classInfo != null && result.referencedMemberName == null) {
 362             // class reference
 363             if (result.label.length() == 0) {
 364                 result.label = result.classInfo.name();
 365             }
 366             result.href = result.classInfo.htmlPage();
 367         }
 368         else if (result.memberInfo != null) {
 369             // member reference
 370             ClassInfo containing = result.memberInfo.containingClass();
 371             if (result.memberInfo.isExecutable()) {
 372                 if (result.referencedMemberName.indexOf('(') < 0) {
 373                     result.referencedMemberName += method.flatSignature();
 374                 }
 375             }
 376             if (result.label.length() == 0) {
 377                 result.label = result.referencedMemberName;
 378             }
 379             result.href = containing.htmlPage() + '#' + result.memberInfo.anchor();
 380         }
 381
 382         if (result.href == null && !skipHref) {
 383             if (printOnErrors && (base == null || base.checkLevel())) {
 384                 Errors.error(Errors.UNRESOLVED_LINK, pos,
 385                         "Unresolved link/see tag \"" + text.trim()
 386                         + "\" in " + ((base != null) ? base.qualifiedName() : "[null]"));
 387             }
 388             result.makeError();
 389         }
 390         else if (result.memberInfo != null && !result.memberInfo.checkLevel()) {
 391             if (printOnErrors && (base == null || base.checkLevel())) {
 392                 Errors.error(Errors.HIDDEN_LINK, pos,
 393                         "Link to hidden member: " + text.trim());
 394                 result.href = null;
 395             }
 396             result.kind = "@seeJustLabel";
 397         }
 398         else if (result.classInfo != null && !result.classInfo.checkLevel()) {
 399             if (printOnErrors && (base == null || base.checkLevel())) {
 400                 Errors.error(Errors.HIDDEN_LINK, pos,
 401                         "Link to hidden class: " + text.trim() + " label=" + result.label);
 402                 result.href = null;
 403             }
 404             result.kind = "@seeJustLabel";
 405         }
 406         else if (result.packageInfo != null && !result.packageInfo.checkLevel()) {
 407             if (printOnErrors && (base == null || base.checkLevel())) {
 408                 Errors.error(Errors.HIDDEN_LINK, pos,
 409                         "Link to hidden package: " + text.trim());
 410                 result.href = null;
 411             }
 412             result.kind = "@seeJustLabel";
 413         }
 414
 415         result.good = true;
 416
 417         return result;
 418     }
 419
 420     public boolean checkLevel() {
 421         if (memberInfo != null) {
 422             return memberInfo.checkLevel();
 423         }
 424         if (classInfo != null) {
 425             return classInfo.checkLevel();
 426         }
 427         if (packageInfo != null) {
 428             return packageInfo.checkLevel();
 429         }
 430         return false;
 431     }
 432
 433     /** turn this LinkReference into one with an error message */
 434     private void makeError() {
 435         //this.href = "ERROR(" + this.text.trim() + ")";
 436         this.href = null;
 437         if (this.label == null) {
 438             this.label = "";
 439         }
 440         this.label = "ERROR(" + this.label + "/" + text.trim() + ")";
 441     }
 442
 443     /** private. **/
 444     private LinkReference() {
 445     }
 446 }