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

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