/*
 * @(#)Configuration.java	1.15 98/09/22
 *
 * Copyright 1997, 1998 by Sun Microsystems, Inc.,
 * 901 San Antonio Road, Palo Alto, California, 94303, U.S.A.
 * All rights reserved.
 *
 * This software is the confidential and proprietary information
 * of Sun Microsystems, Inc. ("Confidential Information").  You
 * shall not disclose such Confidential Information and shall use
 * it only in accordance with the terms of the license agreement
 * you entered into with Sun.
 */

package com.sun.tools.doclets;

import com.sun.javadoc.*;
import java.util.*;
import java.io.*;

/**
 * Configure the output based on the options. Doclets should sub-class 
 * Configuration, to configure and add their own options. This class contains
 * all user options which are supported by the 1.1 doclet and the standard
 * doclet.
 *
 * @author Robert Field.
 * @author Atul Dambalkar.
 */
public abstract class Configuration {
    /**
     * The Root of the generated Program Structure from the Doclet API.
     */
    public static RootDoc root;

    /**
     * Destination directory name, in which doclet will generate the entire
     * documentation. Default is current directory.
     */
    public String destdirname = "";

    /**
     * Encoding for this document. Default is default encoding for this 
     * platform.
     */
    public String docencoding = null;

    /**
     * Encoding for this document. Default is default encoding for this 
     * platform.
     */ 
    public String encoding = null;

    /**
     * Generate author specific information for all the classes if @author 
     * tag is used in the doc comment and if -author option is used.
     * <code>showauthor</code> is set to true if -author option is used.
     * Default is don't show author information. 
     */
    public boolean showauthor = false;

    /**
     * Generate version specific information for the all the classes 
     * if @version tag is used in the doc comment and if -version option is 
     * used. <code>showversion</code> is set to true if -version option is 
     * used.Default is don't show version information. 
     */
    public boolean showversion = false;

    /**
     * Don't generate the date in the generated documentation, if -nodate 
     * option is used. <code>nodate</code> is set to true if -nodate 
     * option is used. Default is don't show date. 
     */
    public boolean nodate = false;

    /**
     * Sourcepath from where to read the source files. Default is classpath.
     * 
     */
    public String sourcepath = "";

    /**
     * Don't generate deprecated API information at all, if -nodeprecated 
     * option is used. <code>nodepracted</code> is set to true if 
     * -nodeprecated option is used. Default is generate deprected API 
     * information.
     */
    public boolean nodeprecated = false;

    /**
     * All the packages to be documented.
     */
    public PackageDoc[] packages;

    /**
     * Message Retriever for the doclet, to retrieve message from the resource
     * file for this Configuration, which is common for 1.1 and standard 
     * doclets.
     */
    public static MessageRetriever message = null;

    /**
     * This method should be defined in all those doclets(configurations), 
     * which want to derive themselves from this Configuration. This method
     * can be used to set its own command line options.
     * 
     * @param root Root of the Program Structure generated by Javadoc.
     */
    public abstract void setSpecificDocletOptions(RootDoc root) 
                                           throws DocletAbortException;

    /**
     * This method should be defined in all those doclets 
     * which want to inherit from this Configuration. This method 
     * should return the number of arguments to the command line option. 
     * This method is called by the method {@link #optionLength(String)}.
     * 
     * @param option Command line option under consideration.
     * @return number of arguments to option. Zero return means
     * option not known.  Negative value means error occurred.
     * @see #optionLength(String)  
     */
    public abstract int specificDocletOptionLength(String option);

    /**
     * This method should be defined in all those doclets 
     * which want to inherit from this Configuration. This method
     * can be used to check the validity of its own command line options. 
     * This method is called by {@link #validOptions(String[][], 
     * DocErrorReporter)}.
     * 
     * @param option   Options-array from the Javadoc.
     * @param reporter Error reporter.
     * @return True if all the options are valid else false.
     */
    public abstract boolean specificDocletValidOptions(String option[][],
                                                   DocErrorReporter reporter);

    /**
     * Constructor. Constructs the message retriever with resource file.
     */
    public Configuration() {
        if (message == null) {
            message =
                new MessageRetriever("com.sun.tools.javadoc.resources.doclets");
        }
    }

    /**
     * Set the command line options supported by this configuration.
     *
     * @param root Root of the Program Structure generated by this Javadoc run.
     */
    public void setOptions(RootDoc root) throws DocletAbortException {
        String[][] options = root.options();
        Configuration.root = root;
        packages = root.specifiedPackages();
        Arrays.sort(packages);
        for (int oi = 0; oi < options.length; ++oi) {
            String[] os = options[oi];
            String opt = os[0].toLowerCase();
            if (opt.equals("-d")) {
                destdirname = addTrailingFileSep(os[1]);
            } else  if (opt.equals("-docencoding")) {
                docencoding = os[1];
            } else  if (opt.equals("-encoding")) {
                encoding = os[1];
            } else  if (opt.equals("-author")) {
                showauthor = true;
            } else  if (opt.equals("-version")) {
                showversion = true;
            } else  if (opt.equals("-nodeprecated")) {
                nodeprecated = true;
            } else  if (opt.equals("-xnodate")) {
                nodate = true;
            } else  if (opt.equals("-sourcepath")) {
                sourcepath = os[1];
            } else if (opt.equals("-classpath") && 
                       sourcepath.length() == 0) {
                sourcepath = os[1];
            }
        }
        if (sourcepath.length() == 0) {
            sourcepath = System.getProperty("env.class.path");
        }
        if (docencoding == null) {
            docencoding = encoding;
        }

        setSpecificDocletOptions(root);
        HtmlDocWriter.configuration = this;
    }

    /**
     * Add a traliling file separator, if not found or strip off extra trailing
     * file separators if any.
     *
     * @param path Path under consideration.
     * @return String Properly constructed path string.
     */
    String addTrailingFileSep(String path) {
	String fs = System.getProperty("file.separator");
        String dblfs = fs + fs;
        int indexDblfs;
        while ((indexDblfs = path.indexOf(dblfs)) >= 0) {
            path = path.substring(0, indexDblfs) + 
                        path.substring(indexDblfs + fs.length());
        }
	if (!path.endsWith(fs))
	    path += fs;
	return path;
    }

   /**
    * Returns the "length" of a given option. If an option takes no
    * arguments, its length is one. If it takes one argument, it's
    * 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(String[][], DocErrorReporter)} to validate them.
    * <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>
    *
    * @return number of arguments + 1 for a option. Zero return means
    * option not known.  Negative value means error occurred.
    */
    public int optionLength(String option) {
        option = option.toLowerCase();
        if (option.equals("-version") ||
            option.equals("-nodeprecated") ||
            option.equals("-author") ||
            option.equals("-xnodate")) {
            return 1;
        } else if (option.equals("-docencoding") ||
                   option.equals("-encoding") ||
                   option.equals("-sourcepath") ||
                   option.equals("-d")) {
            return 2;
        } else {
            return specificDocletOptionLength(option);
        }
    }

    /**
     * After parsing the available options using {@link #optionLength(String)},
     * 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.)
     * This method is not required to be written by sub-classes and will
     * default gracefully (to true) if absent.
     * <P>
     * Printing option related error messages (using the provided
     * DocErrorReporter) is the responsibility of this method.
     *
     * @param options  Options used on the command line.
     * @param reporter Error reporter to be used.
     * @return true if all the options are valid.
     */
    public boolean validOptions(String options[][], 
                                DocErrorReporter reporter) {
        boolean docencodingfound = false;
        String encoding = "";
        for (int oi = 0; oi < options.length; oi++) {
            String[] os = options[oi];
            String opt = os[0].toLowerCase();
            if (opt.equals("-d")) {
                String dd = os[1];
                File destDir = new File(dd);
                if (!destDir.exists()) {
                    reporter.printError(message.getText(
                        "doclet.destination_directory_not_found_0", 
                                                        destDir.getPath()));
                    return false;
                } else if (!destDir.isDirectory()) {
                    reporter.printError(message.getText(
                        "doclet.destination_directory_not_directory_0", 
                                                        destDir.getPath()));
                    return false;
                } else if (!destDir.canWrite()) {
                    reporter.printError(message.getText(
                        "doclet.destination_directory_not_writable_0", 
                                                        destDir.getPath()));
                    return false;
                }
            } else if (opt.equals("-docencoding")) {
                docencodingfound = true;
                if (!checkOutputFileEncoding(os[1], reporter)) {
                    return false;
                }
            } else if (opt.equals("-encoding")) {
                encoding = os[1];
            }
        }
        if (!docencodingfound && encoding.length() > 0) {
  	    if (!checkOutputFileEncoding(encoding, reporter)) {
                    return false;
            }
        }
        return specificDocletValidOptions(options, reporter);
    }

    /**
     * Check the validity of the given Source or Output File encoding on this 
     * platform. 
     *
     * @param docencoding Output file encoding.
     * @param reporter    Error reporter object.
     */
    protected boolean checkOutputFileEncoding(String docencoding,
                                              DocErrorReporter reporter) {
        OutputStream ost= new ByteArrayOutputStream();
        OutputStreamWriter osw = null;
   	try {
            osw = new OutputStreamWriter(ost, docencoding);
        } catch (UnsupportedEncodingException exc) {
            reporter.printError(message.getText(
                                "doclet.Encoding_not_supported", docencoding));
            return false;                  
        } finally {
            try {
                if (osw != null) {
                    osw.close();
                }
            } catch (IOException exc) {
            }
        } 
        return true;
    }       

}