path: root/src/jdiff/Options.java

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