/*******************************************************************************
* Copyright (c)                                                                *
*           2005   Tristan Allwood,                                            *
*           2005   Daniel Burke,                                               *
*           2005   Marc Hull,                                                  *
*           2005   Ekaterina Itskova,                                          *
*           2005   Steve Zymler                                                *
*                                                                              *
* Permission is hereby granted, free of charge, to any person obtaining a      *
* copy of this software and associated documentation files (the                *
* "Software"), to deal in the Software without restriction, including          *
* without limitation the rights to use, copy, modify, merge, publish,          *
* distribute, sublicense, and/or sell copies of the Software, and to           *
* permit persons to whom the Software is furnished to do so, subject to        *
* the following conditions:                                                    *
*                                                                              *
* The above copyright notice and this permission notice shall be included      *
* in all copies or substantial portions of the Software.                       *
*                                                                              *
* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS      *
* OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF                   *
* MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.       *
* IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY         *
* CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,         *
* TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE            *
* SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.                       *
*******************************************************************************/
/*
 * Created on 18-Oct-2004
 *
 */
package uk.ac.ic.doc.kevlar.api.programs.arguments.internal.argumentInfo;

import uk.ac.ic.doc.kevlar.api.programs.IInfoNodeVisitor;
import uk.ac.ic.doc.kevlar.api.programs.IProgramInfoNode;
import uk.ac.ic.doc.kevlar.api.programs.arguments.ArgumentHelp;
import uk.ac.ic.doc.kevlar.api.programs.arguments.IArgumentHelp;
import uk.ac.ic.doc.kevlar.api.programs.arguments.IArgumentVisitor;
import uk.ac.ic.doc.kevlar.api.programs.arguments.IBasicArgumentInfo;
import uk.ac.ic.doc.kevlar.api.programs.arguments.IBasicArgumentValue;
import uk.ac.ic.doc.kevlar.publicUtil.collections.IImmutableSet;
import uk.ac.ic.doc.kevlar.publicUtil.dom.XMLUtil;
import uk.ac.ic.doc.kevlar.publicUtil.strings.StringUtil;

/**
 * Base class for argument information classes Gives complete information about
 * argument including context sensitive help, initial values, wether it is
 * compulsary and more.
 * 
 * Note: As always, javadoc is inherited from IBasicArgumentInfo
 * 
 * @author Daniel Burke
 */
public abstract class AbstractArgumentInfo implements IBasicArgumentInfo,
        Comparable<IProgramInfoNode> {

    private String name; // name of argument

    private boolean compulsary; // is it compulsary?

    private ArgumentHelp argumentHelp; // context sensitive help for argument

    /**
     * 
     * @param name
     *            The name of the argument
     * @param compulsary
     *            is the argument compulsary?
     * @param help
     *            the context sensitive help
     * @throws IllegalArgumentException
     *             if any paramater is null or if the param name is not a valid
     *             Kevlar identifier. Also thrown if param help is not an
     *             ArgumentHelp. To ensure this is never a problem, use factory
     *             methods of ArgumentModelProvider to manufacture help
     */
    public AbstractArgumentInfo(String name, boolean compulsary,
            IArgumentHelp help) {

        if (name == null || !StringUtil.isSimpleIdentifier(name)) {
            throw new IllegalArgumentException("Param name may not be null "
                    + "or have non alphanumeric chars or - or _");
        }

        if (!(help instanceof ArgumentHelp)) {
            throw new IllegalArgumentException("Param help must be of type "
                    + "ArgumentHelp!");
        }

        this.name = name;
        this.compulsary = compulsary;
        this.argumentHelp = (ArgumentHelp) help;
    }

    public abstract void takeVisitor(IArgumentVisitor visitor);

    public boolean equals(Object obj) {
        if (!(obj instanceof AbstractArgumentInfo)) {
            return false;
        }

        return name.equals(((AbstractArgumentInfo) obj).getName());
    }

    public int hashCode() {
        return name.hashCode();
    }
    
    public int compareTo(IProgramInfoNode o) {
        return name.compareTo(o.getName());
    }

    public String getName() {
        return name;
    }

    public boolean isCompulsary() {
        return compulsary;
    }

    /**
     * @return all the children of this argument. These are that may appeaar
     *         when this arguments that may appear when this argument is set
     */
    public abstract IImmutableSet<String> getChildren();

    public ArgumentHelp getArgumentHelp() {
        return argumentHelp;
    }

    public abstract IBasicArgumentValue getInitialValue();

    /**
     * Note: XML DTD that should be generated is found under
     * api.programs.Program.dtd
     * 
     * @return XML that represents the argument info
     */
    public abstract String toString();

    /**
     * Note: XML DTD that should be generated is found under
     * api.programs.Program.dtd
     * 
     * @return XML that represents the argument info
     * @param depth
     *            XML will be tab indented to this depth
     */
    public abstract String toString(int depth);

    /**
     * May be used by subclasses to print out &lt;argument&gt; XML.
     * 
     * @param depth
     *            XML will be tab indented to this depth
     * @param specialisedBody
     *            any XML to insert at the bottom. This should contain the
     *            specialised XML tag
     * @return XML that represents the argument info
     */
    protected String toString(int depth, String specialisedBody) {
        StringBuilder text = new StringBuilder();

        depth = XMLUtil.putOpenElem(text, "argument", depth);

        XMLUtil.putElement(text, "name", name, depth);

        text.append(argumentHelp.toString(depth));

        if (compulsary) {
            XMLUtil.putElement(text, "is-compulsary", null, depth);
        }

        // Add specialised XML component
        text.append(specialisedBody);

        depth = XMLUtil.putCloseElem(text, "argument", depth);

        return text.toString();
    }
    
    public void takeInfoNodeVisitor(IInfoNodeVisitor v)
    {
        v.argumentInfo(this);
    }
}