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;
|
}
|
