From 50014a564f8c39e41d3113f71d47b7ec4e9e3550 Mon Sep 17 00:00:00 2001 From: Vincent Siveton Date: Sat, 8 Mar 2008 13:44:45 +0000 Subject: [PATCH] MPLUGIN-90: Refactor makeValidHtml into PluginUtils for better reusage Submitted by: Benjamin Bentmann Reviewed by: Vincent Siveton o applied git-svn-id: https://svn.apache.org/repos/asf/maven/plugin-tools/trunk@634963 13f79535-47bb-0310-9956-ffa450edef68 --- .../maven/plugin/plugin/PluginReport.java | 4 + .../plugin/generator/PluginXdocGenerator.java | 159 +----------------- .../maven/tools/plugin/util/PluginUtils.java | 152 +++++++++++++++++ .../generator/PluginXdocGeneratorTest.java | 69 +------- .../tools/plugin/util/PluginUtilsTest.java | 72 +++++++- 5 files changed, 231 insertions(+), 225 deletions(-) diff --git a/maven-plugin-plugin/src/main/java/org/apache/maven/plugin/plugin/PluginReport.java b/maven-plugin-plugin/src/main/java/org/apache/maven/plugin/plugin/PluginReport.java index 5f29564..4107fee 100644 --- a/maven-plugin-plugin/src/main/java/org/apache/maven/plugin/plugin/PluginReport.java +++ b/maven-plugin-plugin/src/main/java/org/apache/maven/plugin/plugin/PluginReport.java @@ -326,6 +326,10 @@ public class PluginReport { description = getBundle( locale ).getString( "report.plugin.goal.nodescription" ); } + else + { + description = PluginUtils.makeHtmlValid( description ); + } String deprecated = mojo.getDeprecated(); if ( StringUtils.isNotEmpty( deprecated ) ) diff --git a/maven-plugin-tools-api/src/main/java/org/apache/maven/tools/plugin/generator/PluginXdocGenerator.java b/maven-plugin-tools-api/src/main/java/org/apache/maven/tools/plugin/generator/PluginXdocGenerator.java index d92884b..9c3c432 100644 --- a/maven-plugin-tools-api/src/main/java/org/apache/maven/tools/plugin/generator/PluginXdocGenerator.java +++ b/maven-plugin-tools-api/src/main/java/org/apache/maven/tools/plugin/generator/PluginXdocGenerator.java @@ -29,8 +29,6 @@ import java.util.Iterator; import java.util.List; import java.util.Locale; import java.util.ResourceBundle; -import java.util.regex.Matcher; -import java.util.regex.Pattern; import org.apache.maven.plugin.descriptor.MojoDescriptor; import org.apache.maven.plugin.descriptor.Parameter; @@ -38,12 +36,9 @@ import org.apache.maven.plugin.descriptor.PluginDescriptor; import org.apache.maven.project.MavenProject; import org.apache.maven.tools.plugin.util.PluginUtils; import org.codehaus.plexus.util.IOUtil; -import org.codehaus.plexus.util.StringInputStream; -import org.codehaus.plexus.util.StringOutputStream; import org.codehaus.plexus.util.StringUtils; import org.codehaus.plexus.util.xml.PrettyPrintXMLWriter; import org.codehaus.plexus.util.xml.XMLWriter; -import org.w3c.tidy.Tidy; /** * @todo add example usage tag that can be shown in the doco @@ -177,7 +172,7 @@ public class PluginXdocGenerator w.startElement( "p" ); if ( StringUtils.isNotEmpty( mojoDescriptor.getDescription() ) ) { - w.writeMarkup( makeHtmlValid( mojoDescriptor.getDescription() ) ); + w.writeMarkup( PluginUtils.makeHtmlValid( mojoDescriptor.getDescription() ) ); } else { @@ -384,7 +379,7 @@ public class PluginXdocGenerator } else { - description = makeHtmlValid( description ); + description = PluginUtils.makeHtmlValid( description ); } w.startElement( "p" ); w.writeMarkup( description ); @@ -520,7 +515,7 @@ public class PluginXdocGenerator } else { - description = makeHtmlValid( description ); + description = PluginUtils.makeHtmlValid( description ); } if ( StringUtils.isNotEmpty( parameter.getDeprecated() ) ) { @@ -559,154 +554,6 @@ public class PluginXdocGenerator return list; } - /** - * @param description Javadoc description with HTML tags - * @return the description with valid HTML tags - */ - protected static String makeHtmlValid( String description ) - { - if ( StringUtils.isEmpty( description ) ) - { - return ""; - } - - StringOutputStream out = new StringOutputStream(); - - // Using jTidy to clean comment - Tidy tidy = new Tidy(); - tidy.setDocType( "loose" ); - tidy.setXHTML( true ); - tidy.setXmlOut( true ); - tidy.setMakeClean( true ); - tidy.setQuiet( true ); - tidy.setShowWarnings( false ); - tidy.parse( new StringInputStream( decodeJavadocTags( description ) ), out ); - - // strip the header/body stuff - String LS = System.getProperty( "line.separator" ); - String commentCleaned = out.toString(); - if ( StringUtils.isEmpty( commentCleaned ) ) - { - return ""; - } - int startPos = commentCleaned.indexOf( "" + LS ) + 6 + LS.length(); - int endPos = commentCleaned.indexOf( LS + "" ); - - return commentCleaned.substring( startPos, endPos ); - } - - /** - * Decodes javadoc inline tags into equivalent HTML tags. For instance, the inline tag "{@code }" should be - * rendered as "<A&B>". - * - * @param description The javadoc description to decode, may be null. - * @return The decoded description, never null. - */ - protected static String decodeJavadocTags( String description ) - { - if ( StringUtils.isEmpty( description ) ) - { - return ""; - } - - StringBuffer decoded = new StringBuffer( description.length() + 1024 ); - - Matcher matcher = Pattern.compile( "\\{@(\\w+)\\s*([^\\}]*)\\}" ).matcher( description ); - while ( matcher.find() ) - { - String tag = matcher.group( 1 ); - String text = matcher.group( 2 ); - text = StringUtils.replace( text, "&", "&" ); - text = StringUtils.replace( text, "<", "<" ); - text = StringUtils.replace( text, ">", ">" ); - if ( "code".equals( tag ) ) - { - text = "" + text + ""; - } - else if ( "link".equals( tag ) || "linkplain".equals( tag ) || "value".equals( tag ) ) - { - String pattern = "(([^#\\.\\s]+\\.)*([^#\\.\\s]+))?" + "(#([^\\(\\s]*)(\\([^\\)]*\\))?\\s*(\\S.*)?)?"; - final int LABEL = 7; - final int CLASS = 3; - final int MEMBER = 5; - final int ARGS = 6; - Matcher link = Pattern.compile( pattern ).matcher( text ); - if ( link.matches() ) - { - text = link.group( LABEL ); - if ( StringUtils.isEmpty( text ) ) - { - text = link.group( CLASS ); - if ( StringUtils.isEmpty( text ) ) - { - text = ""; - } - if ( StringUtils.isNotEmpty( link.group( MEMBER ) ) ) - { - if ( StringUtils.isNotEmpty( text ) ) - { - text += '.'; - } - text += link.group( MEMBER ); - if ( StringUtils.isNotEmpty( link.group( ARGS ) ) ) - { - text += "()"; - } - } - } - } - if ( !"linkplain".equals( tag ) ) - { - text = "" + text + ""; - } - } - matcher.appendReplacement( decoded, ( text != null ) ? quoteReplacement( text ) : "" ); - } - matcher.appendTail( decoded ); - - return decoded.toString(); - } - - /** - * Returns a literal replacement String for the specified String. This method - * produces a String that will work as a literal replacement s in the - * appendReplacement method of the {@link Matcher} class. The String produced will - * match the sequence of characters in s treated as a literal sequence. Slashes ('\') and dollar - * signs ('$') will be given no special meaning. - * - * TODO: copied from Matcher class of Java 1.5, remove once target platform can be upgraded - * @see - * http://java.sun.com/j2se/1.5.0/docs/api/java/util/regex/Matcher.html - * - * @param s The string to be literalized - * @return A literal string replacement - */ - private static String quoteReplacement( String s ) - { - if ( ( s.indexOf( '\\' ) == -1 ) && ( s.indexOf( '$' ) == -1 ) ) - return s; - StringBuffer sb = new StringBuffer(); - for ( int i = 0; i < s.length(); i++ ) - { - char c = s.charAt( i ); - if ( c == '\\' ) - { - sb.append( '\\' ); - sb.append( '\\' ); - } - else if ( c == '$' ) - { - sb.append( '\\' ); - sb.append( '$' ); - } - else - { - sb.append( c ); - } - } - return sb.toString(); - } - /** * Gets the resource bundle for the specified locale. * diff --git a/maven-plugin-tools-api/src/main/java/org/apache/maven/tools/plugin/util/PluginUtils.java b/maven-plugin-tools-api/src/main/java/org/apache/maven/tools/plugin/util/PluginUtils.java index 6b3be61..e55bbf9 100644 --- a/maven-plugin-tools-api/src/main/java/org/apache/maven/tools/plugin/util/PluginUtils.java +++ b/maven-plugin-tools-api/src/main/java/org/apache/maven/tools/plugin/util/PluginUtils.java @@ -27,6 +27,8 @@ import java.util.ArrayList; import java.util.Iterator; import java.util.LinkedList; import java.util.List; +import java.util.regex.Matcher; +import java.util.regex.Pattern; import org.apache.maven.artifact.DependencyResolutionRequiredException; import org.apache.maven.model.Dependency; @@ -36,8 +38,11 @@ import org.apache.maven.reporting.MavenReport; import org.codehaus.plexus.component.repository.ComponentDependency; import org.codehaus.plexus.util.DirectoryScanner; import org.codehaus.plexus.util.FileUtils; +import org.codehaus.plexus.util.StringInputStream; +import org.codehaus.plexus.util.StringOutputStream; import org.codehaus.plexus.util.StringUtils; import org.codehaus.plexus.util.xml.XMLWriter; +import org.w3c.tidy.Tidy; /** * Convenience methods to play with Maven plugins. @@ -221,4 +226,151 @@ public final class PluginUtils return false; } + + /** + * @param description Javadoc description with HTML tags + * @return the description with valid HTML tags + */ + public static String makeHtmlValid( String description ) + { + if ( StringUtils.isEmpty( description ) ) + { + return ""; + } + + StringOutputStream out = new StringOutputStream(); + + // Using jTidy to clean comment + Tidy tidy = new Tidy(); + tidy.setDocType( "loose" ); + tidy.setXHTML( true ); + tidy.setXmlOut( true ); + tidy.setMakeClean( true ); + tidy.setQuiet( true ); + tidy.setShowWarnings( false ); + tidy.parse( new StringInputStream( decodeJavadocTags( description ) ), out ); + + // strip the header/body stuff + String LS = System.getProperty( "line.separator" ); + String commentCleaned = out.toString(); + if ( StringUtils.isEmpty( commentCleaned ) ) + { + return ""; + } + int startPos = commentCleaned.indexOf( "" + LS ) + 6 + LS.length(); + int endPos = commentCleaned.indexOf( LS + "" ); + + return commentCleaned.substring( startPos, endPos ); + } + + /** + * Decodes javadoc inline tags into equivalent HTML tags. For instance, the inline tag "{@code }" should be + * rendered as "<A&B>". + * + * @param description The javadoc description to decode, may be null. + * @return The decoded description, never null. + */ + static String decodeJavadocTags( String description ) + { + if ( StringUtils.isEmpty( description ) ) + { + return ""; + } + + StringBuffer decoded = new StringBuffer( description.length() + 1024 ); + + Matcher matcher = Pattern.compile( "\\{@(\\w+)\\s*([^\\}]*)\\}" ).matcher( description ); + while ( matcher.find() ) + { + String tag = matcher.group( 1 ); + String text = matcher.group( 2 ); + text = StringUtils.replace( text, "&", "&" ); + text = StringUtils.replace( text, "<", "<" ); + text = StringUtils.replace( text, ">", ">" ); + if ( "code".equals( tag ) ) + { + text = "" + text + ""; + } + else if ( "link".equals( tag ) || "linkplain".equals( tag ) || "value".equals( tag ) ) + { + String pattern = "(([^#\\.\\s]+\\.)*([^#\\.\\s]+))?" + "(#([^\\(\\s]*)(\\([^\\)]*\\))?\\s*(\\S.*)?)?"; + final int LABEL = 7; + final int CLASS = 3; + final int MEMBER = 5; + final int ARGS = 6; + Matcher link = Pattern.compile( pattern ).matcher( text ); + if ( link.matches() ) + { + text = link.group( LABEL ); + if ( StringUtils.isEmpty( text ) ) + { + text = link.group( CLASS ); + if ( StringUtils.isEmpty( text ) ) + { + text = ""; + } + if ( StringUtils.isNotEmpty( link.group( MEMBER ) ) ) + { + if ( StringUtils.isNotEmpty( text ) ) + { + text += '.'; + } + text += link.group( MEMBER ); + if ( StringUtils.isNotEmpty( link.group( ARGS ) ) ) + { + text += "()"; + } + } + } + } + if ( !"linkplain".equals( tag ) ) + { + text = "" + text + ""; + } + } + matcher.appendReplacement( decoded, ( text != null ) ? quoteReplacement( text ) : "" ); + } + matcher.appendTail( decoded ); + + return decoded.toString(); + } + + /** + * Returns a literal replacement String for the specified String. This method + * produces a String that will work as a literal replacement s in the + * appendReplacement method of the {@link Matcher} class. The String produced will + * match the sequence of characters in s treated as a literal sequence. Slashes ('\') and dollar + * signs ('$') will be given no special meaning. TODO: copied from Matcher class of Java 1.5, remove once target + * platform can be upgraded + * + * @see java.util.regex.Matcher + * @param s The string to be literalized + * @return A literal string replacement + */ + private static String quoteReplacement( String s ) + { + if ( ( s.indexOf( '\\' ) == -1 ) && ( s.indexOf( '$' ) == -1 ) ) + return s; + StringBuffer sb = new StringBuffer(); + for ( int i = 0; i < s.length(); i++ ) + { + char c = s.charAt( i ); + if ( c == '\\' ) + { + sb.append( '\\' ); + sb.append( '\\' ); + } + else if ( c == '$' ) + { + sb.append( '\\' ); + sb.append( '$' ); + } + else + { + sb.append( c ); + } + } + return sb.toString(); + } + } diff --git a/maven-plugin-tools-api/src/test/java/org/apache/maven/tools/plugin/generator/PluginXdocGeneratorTest.java b/maven-plugin-tools-api/src/test/java/org/apache/maven/tools/plugin/generator/PluginXdocGeneratorTest.java index 3c4c99f..f14b467 100644 --- a/maven-plugin-tools-api/src/test/java/org/apache/maven/tools/plugin/generator/PluginXdocGeneratorTest.java +++ b/maven-plugin-tools-api/src/test/java/org/apache/maven/tools/plugin/generator/PluginXdocGeneratorTest.java @@ -27,72 +27,5 @@ package org.apache.maven.tools.plugin.generator; public class PluginXdocGeneratorTest extends AbstractGeneratorTestCase { - public void testMakeHtmlValid() - { - String javadoc = ""; - assertEquals( "", PluginXdocGenerator.makeHtmlValid( javadoc ) ); - - // true HTML - javadoc = "Generates something for the project."; - assertEquals( "Generates something for the project.", PluginXdocGenerator.makeHtmlValid( javadoc ) ); - - // wrong HTML - javadoc = "Generates something for the project."; - assertEquals( "Generates something for the project.", PluginXdocGenerator - .makeHtmlValid( javadoc ) ); - } - - public void testDecodeJavadocTags() - { - String javadoc = null; - assertEquals( "", PluginXdocGenerator.decodeJavadocTags( javadoc ) ); - - javadoc = ""; - assertEquals( "", PluginXdocGenerator.decodeJavadocTags( javadoc ) ); - - javadoc = "{@code text}"; - assertEquals( "text", PluginXdocGenerator.decodeJavadocTags( javadoc ) ); - - javadoc = "{@code }"; - assertEquals( "<A&B>", PluginXdocGenerator.decodeJavadocTags( javadoc ) ); - - javadoc = "{@literal text}"; - assertEquals( "text", PluginXdocGenerator.decodeJavadocTags( javadoc ) ); - - javadoc = "{@literal text} {@literal text}"; - assertEquals( "text text", PluginXdocGenerator.decodeJavadocTags( javadoc ) ); - - javadoc = "{@literal }"; - assertEquals( "<A&B>", PluginXdocGenerator.decodeJavadocTags( javadoc ) ); - - javadoc = "{@link Class}"; - assertEquals( "Class", PluginXdocGenerator.decodeJavadocTags( javadoc ) ); - - javadoc = "{@linkplain Class}"; - assertEquals( "Class", PluginXdocGenerator.decodeJavadocTags( javadoc ) ); - - javadoc = "{@linkplain #field}"; - assertEquals( "field", PluginXdocGenerator.decodeJavadocTags( javadoc ) ); - - javadoc = "{@linkplain Class#field}"; - assertEquals( "Class.field", PluginXdocGenerator.decodeJavadocTags( javadoc ) ); - - javadoc = "{@linkplain #method()}"; - assertEquals( "method()", PluginXdocGenerator.decodeJavadocTags( javadoc ) ); - - javadoc = "{@linkplain #method(Object arg)}"; - assertEquals( "method()", PluginXdocGenerator.decodeJavadocTags( javadoc ) ); - - javadoc = "{@linkplain #method(Object, String)}"; - assertEquals( "method()", PluginXdocGenerator.decodeJavadocTags( javadoc ) ); - - javadoc = "{@linkplain #method(Object, String) label}"; - assertEquals( "label", PluginXdocGenerator.decodeJavadocTags( javadoc ) ); - - javadoc = "{@linkplain Class#method(Object, String)}"; - assertEquals( "Class.method()", PluginXdocGenerator.decodeJavadocTags( javadoc ) ); - - javadoc = "{@linkplain Class#method(Object, String) label}"; - assertEquals( "label", PluginXdocGenerator.decodeJavadocTags( javadoc ) ); - } + // inherits tests from base class } diff --git a/maven-plugin-tools-api/src/test/java/org/apache/maven/tools/plugin/util/PluginUtilsTest.java b/maven-plugin-tools-api/src/test/java/org/apache/maven/tools/plugin/util/PluginUtilsTest.java index 551b4cd..1856239 100644 --- a/maven-plugin-tools-api/src/test/java/org/apache/maven/tools/plugin/util/PluginUtilsTest.java +++ b/maven-plugin-tools-api/src/test/java/org/apache/maven/tools/plugin/util/PluginUtilsTest.java @@ -118,4 +118,74 @@ public class PluginUtilsTest impl = "org.apache.maven.tools.plugin.util.stubs.MojoStub"; assertFalse( PluginUtils.isMavenReport( impl, stub ) ); } -} \ No newline at end of file + + public void testMakeHtmlValid() + { + String javadoc = ""; + assertEquals( "", PluginUtils.makeHtmlValid( javadoc ) ); + + // true HTML + javadoc = "Generates something for the project."; + assertEquals( "Generates something for the project.", PluginUtils.makeHtmlValid( javadoc ) ); + + // wrong HTML + javadoc = "Generates something for the project."; + assertEquals( "Generates something for the project.", PluginUtils + .makeHtmlValid( javadoc ) ); + } + + public void testDecodeJavadocTags() + { + String javadoc = null; + assertEquals( "", PluginUtils.decodeJavadocTags( javadoc ) ); + + javadoc = ""; + assertEquals( "", PluginUtils.decodeJavadocTags( javadoc ) ); + + javadoc = "{@code text}"; + assertEquals( "text", PluginUtils.decodeJavadocTags( javadoc ) ); + + javadoc = "{@code }"; + assertEquals( "<A&B>", PluginUtils.decodeJavadocTags( javadoc ) ); + + javadoc = "{@literal text}"; + assertEquals( "text", PluginUtils.decodeJavadocTags( javadoc ) ); + + javadoc = "{@literal text} {@literal text}"; + assertEquals( "text text", PluginUtils.decodeJavadocTags( javadoc ) ); + + javadoc = "{@literal }"; + assertEquals( "<A&B>", PluginUtils.decodeJavadocTags( javadoc ) ); + + javadoc = "{@link Class}"; + assertEquals( "Class", PluginUtils.decodeJavadocTags( javadoc ) ); + + javadoc = "{@linkplain Class}"; + assertEquals( "Class", PluginUtils.decodeJavadocTags( javadoc ) ); + + javadoc = "{@linkplain #field}"; + assertEquals( "field", PluginUtils.decodeJavadocTags( javadoc ) ); + + javadoc = "{@linkplain Class#field}"; + assertEquals( "Class.field", PluginUtils.decodeJavadocTags( javadoc ) ); + + javadoc = "{@linkplain #method()}"; + assertEquals( "method()", PluginUtils.decodeJavadocTags( javadoc ) ); + + javadoc = "{@linkplain #method(Object arg)}"; + assertEquals( "method()", PluginUtils.decodeJavadocTags( javadoc ) ); + + javadoc = "{@linkplain #method(Object, String)}"; + assertEquals( "method()", PluginUtils.decodeJavadocTags( javadoc ) ); + + javadoc = "{@linkplain #method(Object, String) label}"; + assertEquals( "label", PluginUtils.decodeJavadocTags( javadoc ) ); + + javadoc = "{@linkplain Class#method(Object, String)}"; + assertEquals( "Class.method()", PluginUtils.decodeJavadocTags( javadoc ) ); + + javadoc = "{@linkplain Class#method(Object, String) label}"; + assertEquals( "label", PluginUtils.decodeJavadocTags( javadoc ) ); + } + +}