| package jdiff; |
| |
| import java.io.*; |
| import java.util.*; |
| import com.sun.javadoc.*; |
| |
| /** |
| * Class to handle options for JDiff. |
| * |
| * See the file LICENSE.txt for copyright details. |
| * @author Matthew Doar, mdoar@pobox.com |
| */ |
| public class Options { |
| |
| /** Default constructor. */ |
| public Options() { |
| } |
| |
| /** |
| * Returns the "length" of a given option. If an option takes no |
| * arguments, its length is one. If it takes one argument, its |
| * length is two, and so on. This method is called by Javadoc to |
| * parse the options it does not recognize. It then calls |
| * {@link #validOptions} to validate them. |
| * <blockquote> |
| * <b>Note:</b><br> |
| * The options arrive as case-sensitive strings. For options that |
| * are not case-sensitive, use toLowerCase() on the option string |
| * before comparing it. |
| * </blockquote> |
| * |
| * @param option a String containing an option |
| * @return an int telling how many components that option has |
| */ |
| public static int optionLength(String option) { |
| String opt = option.toLowerCase(); |
| |
| // Standard options |
| if (opt.equals("-authorid")) return 2; |
| if (opt.equals("-versionid")) return 2; |
| if (opt.equals("-d")) return 2; |
| if (opt.equals("-classlist")) return 1; |
| if (opt.equals("-title")) return 2; |
| if (opt.equals("-docletid")) return 1; |
| if (opt.equals("-evident")) return 2; |
| if (opt.equals("-skippkg")) return 2; |
| if (opt.equals("-skipclass")) return 2; |
| if (opt.equals("-execdepth")) return 2; |
| if (opt.equals("-help")) return 1; |
| if (opt.equals("-version")) return 1; |
| if (opt.equals("-package")) return 1; |
| if (opt.equals("-protected")) return 1; |
| if (opt.equals("-public")) return 1; |
| if (opt.equals("-private")) return 1; |
| if (opt.equals("-sourcepath")) return 2; |
| |
| // Options to control JDiff |
| if (opt.equals("-apiname")) return 2; |
| if (opt.equals("-oldapi")) return 2; |
| if (opt.equals("-newapi")) return 2; |
| |
| // Options to control the location of the XML files |
| if (opt.equals("-apidir")) return 2; |
| if (opt.equals("-oldapidir")) return 2; |
| if (opt.equals("-newapidir")) return 2; |
| if (opt.equals("-usercommentsdir")) return 2; |
| |
| |
| // Options for the exclusion level for classes and members |
| if (opt.equals("-excludeclass")) return 2; |
| if (opt.equals("-excludemember")) return 2; |
| |
| if (opt.equals("-firstsentence")) return 1; |
| if (opt.equals("-docchanges")) return 1; |
| if (opt.equals("-packagesonly")) return 1; |
| if (opt.equals("-showallchanges")) return 1; |
| |
| // Option to change the location for the existing Javadoc |
| // documentation for the new API. Default is "../" |
| if (opt.equals("-javadocnew")) return 2; |
| // Option to change the location for the existing Javadoc |
| // documentation for the old API. Default is null. |
| if (opt.equals("-javadocold")) return 2; |
| |
| if (opt.equals("-baseuri")) return 2; |
| |
| // Option not to suggest comments at all |
| if (opt.equals("-nosuggest")) return 2; |
| |
| // Option to enable checking that the comments end with a period. |
| if (opt.equals("-checkcomments")) return 1; |
| // Option to retain non-printing characters in comments. |
| if (opt.equals("-retainnonprinting")) return 1; |
| // Option for the name of the exclude tag |
| if (opt.equals("-excludetag")) return 2; |
| // Generate statistical output |
| if (opt.equals("-stats")) return 1; |
| |
| // Set the browser window title |
| if (opt.equals("-windowtitle")) return 2; |
| // Set the report title |
| if (opt.equals("-doctitle")) return 2; |
| |
| return 0; |
| }//optionLength() |
| |
| /** |
| * After parsing the available options using {@link #optionLength}, |
| * Javadoc invokes this method with an array of options-arrays, where |
| * the first item in any array is the option, and subsequent items in |
| * that array are its arguments. So, if -print is an option that takes |
| * no arguments, and -copies is an option that takes 1 argument, then |
| * <pre> |
| * -print -copies 3 |
| * </pre> |
| * produces an array of arrays that looks like: |
| * <pre> |
| * option[0][0] = -print |
| * option[1][0] = -copies |
| * option[1][1] = 3 |
| * </pre> |
| * (By convention, command line switches start with a "-", but |
| * they don't have to.) |
| * <p> |
| * <b>Note:</b><br> |
| * Javadoc passes <i>all</i>parameters to this method, not just |
| * those that Javadoc doesn't recognize. The only way to |
| * identify unexpected arguments is therefore to check for every |
| * Javadoc parameter as well as doclet parameters. |
| * |
| * @param options an array of String arrays, one per option |
| * @param reporter a DocErrorReporter for generating error messages |
| * @return true if no errors were found, and all options are |
| * valid |
| */ |
| public static boolean validOptions(String[][] options, |
| DocErrorReporter reporter) { |
| final DocErrorReporter errOut = reporter; |
| |
| // A nice object-oriented way of handling errors. An instance of this |
| // class puts out an error message and keeps track of whether or not |
| // an error was found. |
| class ErrorHandler { |
| boolean noErrorsFound = true; |
| void msg(String msg) { |
| noErrorsFound = false; |
| errOut.printError(msg); |
| } |
| } |
| |
| ErrorHandler err = new ErrorHandler(); |
| if (trace) |
| System.out.println("Command line arguments: "); |
| for (int i = 0; i < options.length; i++) { |
| for (int j = 0; j < options[i].length; j++) { |
| Options.cmdOptions += " " + options[i][j]; |
| if (trace) |
| System.out.print(" " + options[i][j]); |
| } |
| } |
| if (trace) |
| System.out.println(); |
| |
| for (int i = 0; i < options.length; i++) { |
| if (options[i][0].toLowerCase().equals("-apiname")) { |
| if (options[i].length < 2) { |
| err.msg("No version identifier specified after -apiname option."); |
| } else if (JDiff.compareAPIs) { |
| err.msg("Use the -apiname option, or the -oldapi and -newapi options, but not both."); |
| } else { |
| String filename = options[i][1]; |
| RootDocToXML.apiIdentifier = filename; |
| filename = filename.replace(' ', '_'); |
| RootDocToXML.outputFileName = filename + ".xml"; |
| JDiff.writeXML = true; |
| JDiff.compareAPIs = false; |
| } |
| continue; |
| } |
| if (options[i][0].toLowerCase().equals("-apidir")) { |
| if (options[i].length < 2) { |
| err.msg("No directory specified after -apidir option."); |
| } else { |
| RootDocToXML.outputDirectory = options[i][1]; |
| } |
| continue; |
| } |
| if (options[i][0].toLowerCase().equals("-oldapi")) { |
| if (options[i].length < 2) { |
| err.msg("No version identifier specified after -oldapi option."); |
| } else if (JDiff.writeXML) { |
| err.msg("Use the -apiname or -oldapi option, but not both."); |
| } else { |
| String filename = options[i][1]; |
| filename = filename.replace(' ', '_'); |
| JDiff.oldFileName = filename + ".xml"; |
| JDiff.writeXML = false; |
| JDiff.compareAPIs = true; |
| } |
| continue; |
| } |
| if (options[i][0].toLowerCase().equals("-oldapidir")) { |
| if (options[i].length < 2) { |
| err.msg("No directory specified after -oldapidir option."); |
| } else { |
| JDiff.oldDirectory = options[i][1]; |
| } |
| continue; |
| } |
| if (options[i][0].toLowerCase().equals("-newapi")) { |
| if (options[i].length < 2) { |
| err.msg("No version identifier specified after -newapi option."); |
| } else if (JDiff.writeXML) { |
| err.msg("Use the -apiname or -newapi option, but not both."); |
| } else { |
| String filename = options[i][1]; |
| filename = filename.replace(' ', '_'); |
| JDiff.newFileName = filename + ".xml"; |
| JDiff.writeXML = false; |
| JDiff.compareAPIs = true; |
| } |
| continue; |
| } |
| if (options[i][0].toLowerCase().equals("-newapidir")) { |
| if (options[i].length < 2) { |
| err.msg("No directory specified after -newapidir option."); |
| } else { |
| JDiff.newDirectory = options[i][1]; |
| } |
| continue; |
| } |
| if (options[i][0].toLowerCase().equals("-usercommentsdir")) { |
| if (options[i].length < 2) { |
| err.msg("Android: No directory specified after -usercommentsdir option."); |
| } else { |
| HTMLReportGenerator.commentsDir = options[i][1]; |
| } |
| continue; |
| } |
| if (options[i][0].toLowerCase().equals("-d")) { |
| if (options[i].length < 2) { |
| err.msg("No directory specified after -d option."); |
| } else { |
| HTMLReportGenerator.outputDir = options[i][1]; |
| } |
| continue; |
| } |
| if (options[i][0].toLowerCase().equals("-javadocnew")) { |
| if (options[i].length < 2) { |
| err.msg("No location specified after -javadocnew option."); |
| } else { |
| HTMLReportGenerator.newDocPrefix = options[i][1]; |
| } |
| continue; |
| } |
| if (options[i][0].toLowerCase().equals("-javadocold")) { |
| if (options[i].length < 2) { |
| err.msg("No location specified after -javadocold option."); |
| } else { |
| HTMLReportGenerator.oldDocPrefix = options[i][1]; |
| } |
| continue; |
| } |
| if (options[i][0].toLowerCase().equals("-baseuri")) { |
| if (options[i].length < 2) { |
| err.msg("No base location specified after -baseURI option."); |
| } else { |
| RootDocToXML.baseURI = options[i][1]; |
| } |
| continue; |
| } |
| if (options[i][0].toLowerCase().equals("-excludeclass")) { |
| if (options[i].length < 2) { |
| err.msg("No level (public|protected|package|private) specified after -excludeclass option."); |
| } else { |
| String level = options[i][1]; |
| if (level.compareTo("public") != 0 && |
| level.compareTo("protected") != 0 && |
| level.compareTo("package") != 0 && |
| level.compareTo("private") != 0) { |
| err.msg("Level specified after -excludeclass option must be one of (public|protected|package|private)."); |
| } else { |
| RootDocToXML.classVisibilityLevel = level; |
| } |
| } |
| continue; |
| } |
| if (options[i][0].toLowerCase().equals("-excludemember")) { |
| if (options[i].length < 2) { |
| err.msg("No level (public|protected|package|private) specified after -excludemember option."); |
| } else { |
| String level = options[i][1]; |
| if (level.compareTo("public") != 0 && |
| level.compareTo("protected") != 0 && |
| level.compareTo("package") != 0 && |
| level.compareTo("private") != 0) { |
| err.msg("Level specified after -excludemember option must be one of (public|protected|package|private)."); |
| } else { |
| RootDocToXML.memberVisibilityLevel = level; |
| } |
| } |
| continue; |
| } |
| if (options[i][0].toLowerCase().equals("-firstsentence")) { |
| RootDocToXML.saveAllDocs = false; |
| continue; |
| } |
| if (options[i][0].toLowerCase().equals("-docchanges")) { |
| HTMLReportGenerator.reportDocChanges = true; |
| Diff.noDocDiffs = false; |
| continue; |
| } |
| if (options[i][0].toLowerCase().equals("-packagesonly")) { |
| RootDocToXML.packagesOnly = true; |
| continue; |
| } |
| if (options[i][0].toLowerCase().equals("-showallchanges")) { |
| Diff.showAllChanges = true; |
| continue; |
| } |
| if (options[i][0].toLowerCase().equals("-nosuggest")) { |
| if (options[i].length < 2) { |
| err.msg("No level (all|remove|add|change) specified after -nosuggest option."); |
| } else { |
| String level = options[i][1]; |
| if (level.compareTo("all") != 0 && |
| level.compareTo("remove") != 0 && |
| level.compareTo("add") != 0 && |
| level.compareTo("change") != 0) { |
| err.msg("Level specified after -nosuggest option must be one of (all|remove|add|change)."); |
| } else { |
| if (level.compareTo("removal") == 0) |
| HTMLReportGenerator.noCommentsOnRemovals = true; |
| else if (level.compareTo("add") == 0) |
| HTMLReportGenerator.noCommentsOnAdditions = true; |
| else if (level.compareTo("change") == 0) |
| HTMLReportGenerator.noCommentsOnChanges = true; |
| else if (level.compareTo("all") == 0) { |
| HTMLReportGenerator.noCommentsOnRemovals = true; |
| HTMLReportGenerator.noCommentsOnAdditions = true; |
| HTMLReportGenerator.noCommentsOnChanges = true; |
| } |
| } |
| } |
| continue; |
| } |
| if (options[i][0].toLowerCase().equals("-checkcomments")) { |
| APIHandler.checkIsSentence = true; |
| continue; |
| } |
| if (options[i][0].toLowerCase().equals("-retainnonprinting")) { |
| RootDocToXML.stripNonPrintables = false; |
| continue; |
| } |
| if (options[i][0].toLowerCase().equals("-excludetag")) { |
| if (options[i].length < 2) { |
| err.msg("No exclude tag specified after -excludetag option."); |
| } else { |
| RootDocToXML.excludeTag = options[i][1]; |
| RootDocToXML.excludeTag = RootDocToXML.excludeTag.trim(); |
| RootDocToXML.doExclude = true; |
| } |
| continue; |
| } |
| if (options[i][0].toLowerCase().equals("-stats")) { |
| HTMLReportGenerator.doStats = true; |
| continue; |
| } |
| if (options[i][0].toLowerCase().equals("-doctitle")) { |
| if (options[i].length < 2) { |
| err.msg("No HTML text specified after -doctitle option."); |
| } else { |
| HTMLReportGenerator.docTitle = options[i][1]; |
| } |
| continue; |
| } |
| if (options[i][0].toLowerCase().equals("-windowtitle")) { |
| if (options[i].length < 2) { |
| err.msg("No text specified after -windowtitle option."); |
| } else { |
| HTMLReportGenerator.windowTitle = options[i][1]; |
| } |
| continue; |
| } |
| if (options[i][0].toLowerCase().equals("-version")) { |
| System.out.println("JDiff version: " + JDiff.version); |
| System.exit(0); |
| } |
| if (options[i][0].toLowerCase().equals("-help")) { |
| usage(); |
| System.exit(0); |
| } |
| }//for |
| if (!JDiff.writeXML && !JDiff.compareAPIs) { |
| err.msg("First use the -apiname option to generate an XML file for one API."); |
| err.msg("Then use the -apiname option again to generate another XML file for a different version of the API."); |
| err.msg("Finally use the -oldapi option and -newapi option to generate a report about how the APIs differ."); |
| } |
| return err.noErrorsFound; |
| }// validOptions() |
| |
| /** Display the arguments for JDiff. */ |
| public static void usage() { |
| System.err.println("JDiff version: " + JDiff.version); |
| System.err.println(""); |
| System.err.println("Valid JDiff arguments:"); |
| System.err.println(""); |
| System.err.println(" -apiname <Name of a version>"); |
| System.err.println(" -oldapi <Name of a version>"); |
| System.err.println(" -newapi <Name of a version>"); |
| |
| System.err.println(" Optional Arguments"); |
| System.err.println(); |
| System.err.println(" -d <directory> Destination directory for output HTML files"); |
| System.err.println(" -oldapidir <directory> Location of the XML file for the old API"); |
| System.err.println(" -newapidir <directory> Location of the XML file for the new API"); |
| System.err.println(" -sourcepath <location of Java source files>"); |
| System.err.println(" -javadocnew <location of existing Javadoc files for the new API>"); |
| System.err.println(" -javadocold <location of existing Javadoc files for the old API>"); |
| System.err.println(" -usercommentsdir <directory> Path to dir containing the user_comments* file(s)"); |
| |
| System.err.println(" -baseURI <base> Use \"base\" as the base location of the various DTDs and Schemas used by JDiff"); |
| System.err.println(" -excludeclass [public|protected|package|private] Exclude classes which are not public, protected etc"); |
| System.err.println(" -excludemember [public|protected|package|private] Exclude members which are not public, protected etc"); |
| |
| System.err.println(" -firstsentence Save only the first sentence of each comment block with the API."); |
| System.err.println(" -docchanges Report changes in Javadoc comments between the APIs"); |
| System.err.println(" -nosuggest [all|remove|add|change] Do not add suggested comments to all, or the removed, added or chabged sections"); |
| System.err.println(" -checkcomments Check that comments are sentences"); |
| System.err.println(" -stripnonprinting Remove non-printable characters from comments."); |
| System.err.println(" -excludetag <tag> Define the Javadoc tag which implies exclusion"); |
| System.err.println(" -stats Generate statistical output"); |
| System.err.println(" -help (generates this output)"); |
| System.err.println(""); |
| System.err.println("For more help, see jdiff.html"); |
| } |
| |
| /** All the options passed on the command line. Logged to XML. */ |
| public static String cmdOptions = ""; |
| |
| /** Set to enable increased logging verbosity for debugging. */ |
| private static boolean trace = false; |
| } |
