libjava/classpath/tools/gnu/classpath/tools/taglets/AuthorTaglet.java

   1 /* gnu.classpath.tools.taglets.AuthorTaglet
   2    Copyright (C) 2001 Free Software Foundation, Inc.
   3
   4 This file is part of GNU Classpath.
   5
   6 GNU Classpath is free software; you can redistribute it and/or modify
   7 it under the terms of the GNU General Public License as published by
   8 the Free Software Foundation; either version 2, or (at your option)
   9 any later version.
  10
  11 GNU Classpath is distributed in the hope that it will be useful, but
  12 WITHOUT ANY WARRANTY; without even the implied warranty of
  13 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  14 General Public License for more details.
  15
  16 You should have received a copy of the GNU General Public License
  17 along with GNU Classpath; see the file COPYING.  If not, write to the
  18 Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA
  19 02111-1307 USA. */
  20
  21 package gnu.classpath.tools.taglets;
  22
  23 import java.util.Map;
  24
  25 import java.util.regex.Pattern;
  26 import java.util.regex.Matcher;
  27
  28 import com.sun.tools.doclets.Taglet;
  29
  30 import com.sun.javadoc.Tag;
  31
  32 /**
  33  *  The default Taglet which handles Author information.
  34  *
  35  *  @author Julian Scheid (julian@sektor37.de)
  36  */
  37 public class AuthorTaglet implements Taglet {
  38
  39    /**
  40     *  Enum class which denotes whether and how to replace email
  41     *  addresses in author tags.
  42     */
  43    public static class EmailReplacement {
  44       private EmailReplacement() {}
  45
  46       /**
  47        *  Specifies that email addresses should not be replaced.
  48        */
  49       public static final EmailReplacement NO_REPLACEMENT = new EmailReplacement();
  50
  51       /**
  52        *  Specifies that author tag text matching "Real Name
  53        *  (user@domain.tld)" is converted to "&lt;a
  54        *  href="mailto:user@domain.tld"&gt;Real Name&lt;/a&gt;.
  55        */
  56       public static final EmailReplacement MAILTO_NAME = new EmailReplacement();
  57
  58       /**
  59        *  Specifies that author tag text matching "Real Name
  60        *  (user@domain.tld)" is converted to "Real Name (&lt;a
  61        *  href="mailto:user@domain.tld"&gt;user@domain.tld&lt;/a&gt;).
  62        */
  63       public static final EmailReplacement NAME_MAILTO_ADDRESS = new EmailReplacement();
  64
  65       /**
  66        *  Specifies that author tag text matching "Real Name
  67        *  (user@domain.tld)" is converted to "Real Name (user AT
  68        *  domain DOT tld)", where the "AT" and "DOT" replacement are
  69        *  specified by AuthorTaglet.emailAtReplacement and
  70        *  AuthorTaglet.emailDotReplacement.
  71        */
  72       public static final EmailReplacement NAME_MANGLED_ADDRESS = new EmailReplacement();
  73    }
  74
  75    private static EmailReplacement emailReplacementType = EmailReplacement.NO_REPLACEMENT;
  76    private static String atReplacement = " <b>at</b> ";
  77    private static String dotReplacement = " <b>dot</b> ";
  78
  79    private static final String NAME = "author";
  80    private static final String SINGLE_HEADER = "Author:";
  81    private static final String MULTI_HEADER = "Authors:";
  82
  83    private static boolean enabled = true;
  84
  85    /**
  86     *  Matches <code>.</code> (dot).
  87     */
  88    private static final Pattern dotPattern = Pattern.compile("[.]");
  89
  90    /**
  91     *  Matches <code>@</code> (at sign).
  92     */
  93    private static final Pattern atPattern = Pattern.compile("[@]");
  94
  95    /**
  96     *  Matches <code>Real Name (user@domain.tld)</code>.
  97     */
  98    private static final Pattern authorEmailPattern
  99      = Pattern.compile("^"
 100                        + "\\s*" // optional whitespace
 101                        + "(" // group #1 start (real name)
 102                        + "(?:[^\t\r\n ]|\\()+" // first name
 103                        + "(?:\\s+(?:[^\t\r\n ]|\\()+)*" // additional names
 104                        + ")" // group #1 end
 105                        + "\\s*" // optional whitespace
 106                        + "[(<]" // opening paren
 107                        + "\\s*" // optional whitespace
 108                        + "(" // group #2 start (email address)
 109                        + "(" // group #3 start (email user)
 110                        + "[A-z0-9_\\-\\.]+" // username
 111                        + ")" // group #3 end
 112                        + "[@]" // at sign
 113                        + "[A-z0-9_\\-]+(?:[.][A-z0-9_\\-]+)+[A-z]" // domain
 114                        + ")" // group #2 end
 115                        + "\\s*" // optional whitespace
 116                        + "(?:\\)|>)" // closing paren
 117                        + "$");
 118
 119    public String getName() {
 120       return NAME;
 121    }
 122
 123    public boolean inField() {
 124       return true;
 125    }
 126
 127    public boolean inConstructor() {
 128       return true;
 129    }
 130
 131    public boolean inMethod() {
 132       return true;
 133    }
 134
 135    public boolean inOverview() {
 136       return true;
 137    }
 138
 139    public boolean inPackage() {
 140       return true;
 141    }
 142
 143    public boolean inType() {
 144       return true;
 145    }
 146
 147    public boolean isInlineTag() {
 148       return false;
 149    }
 150
 151    public static void register(Map tagletMap) {
 152       AuthorTaglet authorTaglet = new AuthorTaglet();
 153       tagletMap.put(authorTaglet.getName(), authorTaglet);
 154    }
 155
 156    public String toString(Tag tag) {
 157       if (enabled) {
 158          return toString(new Tag[] { tag });
 159       }
 160       else {
 161          return null;
 162       }
 163    }
 164
 165    public String toString(Tag[] tags) {
 166       if (!enabled || tags.length == 0) {
 167          return null;
 168       }
 169       else {
 170          boolean haveValidTag = false;
 171          for (int i = 0; i < tags.length && !haveValidTag; ++i) {
 172             if (tags[i].text().length() > 0) {
 173                haveValidTag = true;
 174             }
 175          }
 176
 177          if (haveValidTag) {
 178             StringBuffer result = new StringBuffer();
 179             result.append("<dl class=\"tag list\">");
 180             result.append("<dt class=\"tag section header\"><b>");
 181             if (tags.length == 1) {
 182                result.append(SINGLE_HEADER);
 183             }
 184             else {
 185                result.append(MULTI_HEADER);
 186             }
 187             result.append("</b></dt>");
 188             for (int i = 0; i < tags.length; i++) {
 189                result.append("<dd class=\"tag item\">");
 190                result.append(replaceEmail(tags[i].text()));
 191                result.append("</dd>");
 192             }
 193             result.append("</dl>");
 194             return result.toString();
 195          }
 196          else {
 197             return null;
 198          }
 199       }
 200    }
 201
 202    /**
 203     *  Reformat the tag text according to {@link #emailReplacementType}.
 204     */
 205    private String replaceEmail(String text) {
 206
 207       if (EmailReplacement.NO_REPLACEMENT == emailReplacementType) {
 208          return text;
 209       }
 210       else {
 211          Matcher matcher = authorEmailPattern.matcher(text);
 212          if (matcher.matches()) {
 213             String realName = matcher.group(1);
 214             String emailAddress = matcher.group(2);
 215             if (EmailReplacement.MAILTO_NAME == emailReplacementType) {
 216                return "<a href=\"mailto:" + emailAddress + "\">" + realName + "</a>";
 217             }
 218             else if (EmailReplacement.NAME_MAILTO_ADDRESS == emailReplacementType) {
 219                return realName + " (<a href=\"mailto:" + emailAddress + "\">" + emailAddress + "</a>)";
 220             }
 221             else if (EmailReplacement.NAME_MANGLED_ADDRESS == emailReplacementType) {
 222                Matcher dotMatcher = dotPattern.matcher(emailAddress);
 223                Matcher atMatcher = atPattern.matcher(dotMatcher.replaceAll(dotReplacement));
 224                String mangledAddress = atMatcher.replaceAll(atReplacement);
 225                return realName + " (" + mangledAddress + ")";
 226             }
 227             else {
 228                // this shouldn't happen
 229                return text;
 230             }
 231          }
 232          else {
 233             return text;
 234          }
 235       }
 236    }
 237
 238    /**
 239     *  Set the email replacement type.
 240     */
 241    public static void setEmailReplacementType(EmailReplacement emailReplacementType)
 242    {
 243       if (null == emailReplacementType) {
 244          throw new NullPointerException();
 245       }
 246       AuthorTaglet.emailReplacementType = emailReplacementType;
 247    }
 248
 249    /**
 250     *  Set the HTML text by which the <code>@</code> (at sign) in email
 251     *  addresses should be replaced if the email replacement type is
 252     *  <code>NAME_MANGLED_ADDRESS</code>.
 253     */
 254    public static void setAtReplacement(String atReplacement)
 255    {
 256       AuthorTaglet.atReplacement = atReplacement;
 257    }
 258
 259    /**
 260     *  Set the HTML text by which the <code>.</code> (dot) in email
 261     *  addresses should be replaced if the email replacement type is
 262     *  <code>NAME_MANGLED_ADDRESS</code>.
 263     */
 264    public static void setDotReplacement(String dotReplacement)
 265    {
 266       AuthorTaglet.dotReplacement = dotReplacement;
 267    }
 268
 269    /**
 270     *  Enables/disables this taglet.
 271     */
 272    public static void setTagletEnabled(boolean enabled)
 273    {
 274       AuthorTaglet.enabled = enabled;
 275    }
 276 }