/*
    * $Id: CommandLineArgumentEvaluator.java 178 2010-10-31 18:01:20Z roland $
    * Copyright (C) 2007 Roland Krueger
    * Created on 21.02.2006
    *
    * Author: Roland Krueger (www.rolandkrueger.info)
    *
    * This file is part of RoKlib.
    *
   * This library is free software; you can redistribute it and/or
   * modify it under the terms of the GNU Lesser General Public License
   * as published by the Free Software Foundation; either version 2.1 of
   * the License, or (at your option) any later version.
   *
   * This library is distributed in the hope that it will be useful, but
   * WITHOUT ANY WARRANTY; without even the implied warranty of
   * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
   * Lesser General Public License for more details.
   *
   * You should have received a copy of the GNU Lesser General Public
   * License along with this library; if not, write to the Free Software
   * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307
   * USA
   */
  package info.rolandkrueger.roklib.cli;
  
  import java.util.ArrayList;
  import java.util.Arrays;
  import java.util.Collection;
  import java.util.Collections;
  import java.util.HashSet;
  import java.util.LinkedList;
  import java.util.List;
  import java.util.Set;
  
  /**
   * This class can be used to handle a program's command line options in an easy
   * and uncomplicated way. To use a {@link CommandLineArgumentEvaluator}, you
   * first have to define the set of all available command line options and pass
   * them to the {@link CommandLineArgumentEvaluator} with the
   * {@link CommandLineArgumentEvaluator#addOptions(CommandLineOption...)} or
   * {@link CommandLineArgumentEvaluator#addOptions(Collection)} methods. After
   * that, the evaluator object can be queried if the program was provided with
   * the correct options.
   * 
   * @see CommandLineOption
   * @author Roland Krueger
   */
  public class CommandLineArgumentEvaluator
  {
    /**
     * Enum which is used to describe whether the arguments provided by the user
     * via the command line were valid and if not so, what was wrong about them.
     * After the command line arguments have been evaluated with
     * {@link CommandLineArgumentEvaluator#evaluate()} the result of this
     * evaluation can be queried with
     * {@link CommandLineArgumentEvaluator#getInputStatus()}. This method returns
     * {@link UserInputValidity#OK} if the argument list was valid or some of the
     * other values if it was not. In case of an invalid argument list, the
     * returned value indicates the type of error made by the user.
     * 
     * @see CommandLineArgumentEvaluator#getInputStatus()
     */
    public enum UserInputValidity
    {
      /**
       * Information about the validity of the user input is not yet available.
       * This is only the case after invoking
       * {@link CommandLineArgumentEvaluator#evaluate()}. If
       * {@link CommandLineArgumentEvaluator#getInputStatus()} is called before
       * evaluating the argument list an exception is raised.
       */
      NOT_YET_EVALUATED,
      /**
       * Everything is OK, the user input is valid.
       */
      OK,
      /**
       * The user has given an option that is unknown, i.e. it is not contained in
       * the internal option list.
       */
      UNRECOGNIZED_OPTION,
      /**
       * There are too few options. Not every mandatory option has been provided.
       */
      TOO_FEW_OPTIONS,
      /**
       * The user has either provided a value for a flag option or given more than
       * one values for a singular option.
       */
      TOO_MANY_VALUES,
      /**
       * There are two {@link CommandLineOption}s which have been configured as
       * associate options. Thus, if one of them is used in the argument list, the
       * other option must also be provided. If only one of two associate options
       * is used, though, the input status of this
       * {@link CommandLineArgumentEvaluator} is set to this value.
       */
      MISSING_ASSOCIATE_OPTION,
     /**
      * If a ({@link CommandLineOptionType#LIST}) option or a (
      * {@link CommandLineOptionType#SINGULAR}) option was used like a (
      * {@link CommandLineOptionType#FLAG}) option this type of error will be
      * indicated. I. e., if such an option has not been provided with any value
      * the input status of this {@link CommandLineArgumentEvaluator} is set to
      * this value.
      */
     MISSING_ARGUMENT,
     /**
      * <p>
      * If two options have been configured as being mutually exclusive then
      * using both of them in the argument list will result in this error type.
      * </p>
      * <p>
      * The two mutually exclusive options which have both been used can be
      * queried with
      * {@link CommandLineArgumentEvaluator#getMutuallyExclusiveOptionsBeingUsed()}
      * .
      * </p>
      * 
      */
     MUTUALLY_EXCLUSIVE_OPTIONS_GIVEN,
     /**
      * <p>
      * One option has been given more than once. This option hasn't been
      * configured as an option which can be given multiple times. Therefore, it
      * is not allowed to repeat this option.
      * </p>
      * <p>
      * The duplicate option can be queried with
      * {@link CommandLineArgumentEvaluator#getErroneousOption()}.
      * </p>
      * 
      * @see CommandLineOption#allowOptionRepetition(boolean)
      */
     DUPLICATE_OPTION
   };
 
   private String mShortOptionsMarker = "-";
   private String mLongOptionsMarker = "--";
 
   private Set<CommandLineOption> mOptionSet;
   private Set<CommandLineOption> mMandatoryList;
   private String[] mArgs;
   private UserInputValidity mStatus = UserInputValidity.NOT_YET_EVALUATED;
   private boolean mEvaluated = false;
   private boolean mAllowClusteredShortOptions = true;
   private boolean mAllowStandaloneValues = false;
   private String mDescription;
   private List<String> mStandaloneValues;
 
   private String mUnrecognizedOption;
   private CommandLineOption mErroneousOption;
   private List<CommandLineOption> mMutuallyExclusiveOptionsGiven;
 
   public CommandLineArgumentEvaluator ()
   {
     mOptionSet = new HashSet<CommandLineOption> ();
     mMandatoryList = new HashSet<CommandLineOption> ();
     mDescription = "";
   }
 
   /**
    * Creates a new {@link CommandLineArgumentEvaluator} object that is supposed
    * to check the given command line options.
    * 
    * @param arguments
    *          the command line options for this application as optained by the
    *          <code>main()</code> method, for example
    */
   public CommandLineArgumentEvaluator (String[] arguments)
   {
     this ();
     mArgs = arguments;
   }
 
   public void setArgumentList (String[] args)
   {
     if (args == null) throw new NullPointerException ("Argument list is null.");
     mArgs = args;
   }
 
   /**
    * Adds one or more options to the internal list of all available options.
    * 
    * @param options
    *          an option array which contains all necessary information of a
    *          specific command line option
    */
   public void addOptions (CommandLineOption... options)
   {
     for (CommandLineOption option : options)
     {
       for (CommandLineOption opt : mOptionSet)
       {
         if (opt.equals (option))
           throw new IllegalArgumentException (String.format ("Option %s has already been added.",
               option));
       }
       mOptionSet.add (option);
       if (option.isMandatory ())
       {
         mMandatoryList.add (option);
       }
     }
   }
 
   public void allowClusteredShortOptions (boolean yesNo)
   {
     mAllowClusteredShortOptions = yesNo;
   }
 
   public void allowStandAloneValues (boolean yesNo)
   {
     mAllowStandaloneValues = yesNo;
   }
 
   public List<String> getStandaloneValues ()
   {
     if (! mAllowStandaloneValues)
       throw new IllegalStateException ("Stand-alone values are not allowed for this evaluator.");
 
     if (mStandaloneValues == null) return Collections.emptyList ();
     return mStandaloneValues;
   }
 
   /**
    * Adds a list of {@link CommandLineOption} objects to the internal option
    * list of this evaluator
    * 
    * @param options
    *          a collection of {@link CommandLineOption} objects
    */
   public void addOptions (Collection<CommandLineOption> options)
   {
     for (CommandLineOption option : options)
     {
       addOptions (option);
     }
   }
 
   /**
    * Returns the internal list of {@link CommandLineOption} objects.
    * 
    * @return the internal list of {@link CommandLineOption} objects.
    */
   public Set<CommandLineOption> getOptions ()
   {
     return mOptionSet;
   }
 
   /**
    * After all available options have been configured and added to the evaluator
    * object, the command line options given through the constructor are
    * evaluated, such that after that it can be checked whether the user-provided
    * options are correct or not. Note that this method can only be called once
    * and only once.
    * 
    * @throws IllegalStateException
    *           if this method was called more than once
    */
   public void evaluate ()
   {
     if (mEvaluated) throw new IllegalStateException ("evaluate() has already been called.");
     if (mArgs == null)
       throw new IllegalStateException (
           "No argument list has been set yet. Call setArgumentList() first.");
 
     mEvaluated = true;
     mStatus = UserInputValidity.OK;
 
     List<String> argList = new ArrayList<String> (Arrays.asList (mArgs));
     // first, break up arguments in the form "argument=value" so that they can
     // be evaluated in the same
     // way as all other arguments
     for (String value : new ArrayList<String> (argList))
     {
       if (value.indexOf ('=') != - 1)
       {
         List<String> splitList = splitAtEqualSign (value);
         if (getOptionFor (splitList.get (0), true) != null)
         {
           int index = argList.indexOf (value);
           argList.remove (value);
           if (splitList.size () > 1) argList.add (index, splitList.get (1));
           argList.add (index, splitList.get (0));
         }
       }
     }
 
     CommandLineOption currentOption = null;
 
     // walk over the argument list
     for (String value : argList)
     {
       // try to find an option object for the current argument fragment
       CommandLineOption option = getOptionFor (value, true);
 
       if (option == null && currentOption == null)
       {
         // No option object could be found matching the current argument
         // fragment and
         // there is no current list option to which the current value could be
         // added.
         // Check if the current argument fragment is a flag cluster.
         if (mAllowClusteredShortOptions && value.startsWith (mShortOptionsMarker))
         {
           if (! disassembleFlagCluster (value))
           {
             if (setUnrecognizedOption (value)) return;
           }
         } else
         {
           if (setUnrecognizedOption (value)) return;
         }
       }
 
       if (option == null && currentOption != null)
       {
         // No option could be found but there is a current list option to which
         // the current
         // value could be added
         if (! currentOption.addUserInput (value) && ! disassembleFlagCluster (value))
         {
           mStatus = UserInputValidity.TOO_MANY_VALUES;
           setErroneousOption (currentOption);
           return;
         }
         continue;
       }
 
       if (option != null)
       {
         if (option.isFlag ())
         {
           if (option.isSet () && option.isOptionRepetitionAllowed ())
           {
             option.increaseRepetitions ();
           } else if (option.isSet () && ! option.isOptionRepetitionAllowed ())
           {
             mStatus = UserInputValidity.DUPLICATE_OPTION;
             setErroneousOption (option);
             return;
           } else
           {
             option.set ();
             continue;
           }
         }
         currentOption = option;
         currentOption.set ();
       }
     }
 
     for (CommandLineOption option : mMandatoryList)
     {
       if (! option.isSet ()) mStatus = UserInputValidity.TOO_FEW_OPTIONS;
     }
 
     for (CommandLineOption option : mOptionSet)
     {
       if (option.isSet ())
       {
         if ((option.getType () == CommandLineOptionType.LIST || option.getType () == CommandLineOptionType.SINGULAR)
             && option.getInputList ().length == 0)
         {
           mStatus = UserInputValidity.MISSING_ARGUMENT;
           setErroneousOption (option);
           return;
         }
 
         for (CommandLineOption other : mOptionSet)
         {
           if (option.isMutuallyExclusiveWith (other) && other.isSet ())
           {
             mStatus = UserInputValidity.MUTUALLY_EXCLUSIVE_OPTIONS_GIVEN;
             mMutuallyExclusiveOptionsGiven = new LinkedList<CommandLineOption> ();
             mMutuallyExclusiveOptionsGiven.add (option);
             mMutuallyExclusiveOptionsGiven.add (other);
             return;
           }
 
           if (option.isAssociateTo (other) && ! other.isSet ())
           {
             mStatus = UserInputValidity.MISSING_ASSOCIATE_OPTION;
             setErroneousOption (option);
             return;
           }
         }
       }
     }
   }
 
   private boolean setUnrecognizedOption (String option)
   {
     if (mAllowStandaloneValues)
     {
       if (mStandaloneValues == null) mStandaloneValues = new LinkedList<String> ();
       mStandaloneValues.add (option);
       return false;
     }
     mUnrecognizedOption = option;
     mStatus = UserInputValidity.UNRECOGNIZED_OPTION;
     return true;
   }
 
   public String getUnrecognizedOption ()
   {
     if (mStatus != UserInputValidity.UNRECOGNIZED_OPTION)
       throw new IllegalStateException ("No unrecognized option was given.");
     return mUnrecognizedOption;
   }
 
   private void setErroneousOption (CommandLineOption erroneous)
   {
     mErroneousOption = erroneous;
   }
 
   public CommandLineOption getErroneousOption ()
   {
     if (mErroneousOption == null)
       throw new IllegalStateException ("No option has been set incorrectly.");
     return mErroneousOption;
   }
 
   public String getDescriptiveSummaryFor (CommandLineOption option)
   {
     return getDescriptiveSummaryFor (option, "\n\t\t");
   }
 
   public String getDescriptiveSummaryFor (CommandLineOption option, String descriptionSeparator)
   {
     String description = option.getDescription ();
     String longOption = "";
     if (! option.getLongOption ().equals (""))
       longOption = String.format ("%s%s", getLongOptionsMarker (), option.getLongOption ());
     String shortOption = "";
     if (! option.getShortOption ().equals (""))
       shortOption = String.format ("%s%s", getShortOptionsMarker (), option.getShortOption ());
 
     String separator = description.equals ("") ? "" : descriptionSeparator;
     if (shortOption.equals (""))
       return String.format ("%s%s%s", longOption, separator, description);
 
     if (longOption.equals (""))
       return String.format ("%s%s%s", shortOption, separator, description);
 
     return String.format ("%s, %s%s%s", shortOption, longOption, separator, description);
   }
 
   public List<CommandLineOption> getMutuallyExclusiveOptionsBeingUsed ()
   {
     if (mMutuallyExclusiveOptionsGiven == null)
       throw new IllegalStateException ("No mutually exclusive options have been used");
     return mMutuallyExclusiveOptionsGiven;
   }
 
   private boolean disassembleFlagCluster (String value)
   {
     List<CommandLineOption> optionsToSet = new LinkedList<CommandLineOption> ();
     boolean result = true;
 
     value = value.replaceAll (mShortOptionsMarker, "");
     for (int i = 0; i < value.length (); ++i)
     {
       String flag = String.valueOf (value.charAt (i));
       CommandLineOption option = getOptionFor (flag, false);
       if (option == null)
       {
         result = false;
         break;
       } else
       {
         optionsToSet.add (option);
       }
     }
 
     if (result)
     {
       for (CommandLineOption option : optionsToSet)
       {
         if (option.isOptionRepetitionAllowed ())
         {
           option.increaseRepetitions ();
         } else if (option.isSet ())
         {
           mStatus = UserInputValidity.DUPLICATE_OPTION;
           setErroneousOption (option);
           result = false;
         }
         option.set ();
       }
     }
 
     return result;
   }
 
   private List<String> splitAtEqualSign (String value)
   {
     List<String> result = new LinkedList<String> ();
     assert value.indexOf ('=') != - 1;
 
     result.add (value.substring (0, value.indexOf ('=')));
     result.add (value.substring (value.indexOf ('=') + 1));
     return result;
   }
 
   private CommandLineOption getOptionFor (String value, boolean valueContainsMarker)
   {
     String longOption;
     String shortOption;
 
     for (CommandLineOption option : mOptionSet)
     {
       longOption = valueContainsMarker ? mLongOptionsMarker + option.getLongOption () : option
           .getLongOption ();
       shortOption = valueContainsMarker ? mShortOptionsMarker + option.getShortOption () : option
           .getShortOption ();
       if (shortOption.equals (value) || longOption.equals (value))
       {
         return option;
       }
     }
 
     return null;
   }
 
   public boolean isValid ()
   {
     return getInputStatus () == UserInputValidity.OK;
   }
 
   public void evaluateAndInvokeCallbacks ()
   {
     evaluate ();
     invokeCallbacks ();
   }
 
   public void invokeCallbacks ()
   {
     if (! mEvaluated)
       throw new IllegalStateException (
           "Command line arguments havn't been evaluated yet. Call evaluate() first.");
 
     for (CommandLineOption option : mOptionSet)
     {
       if (option.isSet ())
       {
         option.invokeCallback (this);
       }
     }
   }
 
   /**
    * Returns the status of the command line options given by the user. This
    * method can only be called after invoking method
    * {@link CommandLineArgumentEvaluator#evaluate()}. Otherwise, a
    * {@link IllegalStateException} will be thrown.
    * 
    * @throws IllegalStateException
    *           if this method is called without invoking
    *           {@link CommandLineArgumentEvaluator#evaluate()} beforehand
    * @return the validity status of the user's command line options
    * @see UserInputValidity
    */
   public UserInputValidity getInputStatus ()
   {
     if (mStatus == UserInputValidity.NOT_YET_EVALUATED)
       throw new IllegalStateException (
           "Command line options haven't been evaluated yet. Call evaluate() first.");
     return mStatus;
   }
 
   /**
    * This method will assemble a string containing an overview of all available
    * options together with a general blueprint of how to correctly use these
    * options. Additionally for each option a short description is provided as
    * defined by the respective {@link CommandLineOption} object.
    * 
    * @return a string containing an overview over all available options
    */
   public String getOptionDescription ()
   {
     StringBuffer result = new StringBuffer ();
     String leftBracket;
     String rightBracket;
     String argument;
     String optionString;
     for (CommandLineOption option : mOptionSet)
     {
       if (option.isMandatory ())
       {
         leftBracket = "";
         rightBracket = "";
       } else
       {
         leftBracket = "[";
         rightBracket = "]";
       }
 
       if (option.getType () == CommandLineOptionType.LIST)
         argument = " argument_list...";
       else if (option.getType () == CommandLineOptionType.SINGULAR)
         argument = " argument";
       else
         argument = "";
 
       if (option.getShortOption ().equals (""))
         optionString = option.getLongOption ();
       else if (option.getLongOption ().equals (""))
         optionString = option.getShortOption ();
       else
         optionString = String.format ("(%s|%s)", option.getShortOption (), option.getLongOption ());
 
       result
           .append (String.format ("%s%s%s%s ", leftBracket, optionString, argument, rightBracket));
     }
     return result.toString ();
   }
 
   /**
    * If after having specified the set of available and mandatory options and
    * having called {@link CommandLineArgumentEvaluator#evaluate()} the user has
    * omitted one or more of the mandatory options, these missing options can be
    * queried as a list.
    * 
    * @return list of mandatory options that were omitted by the user
    */
   public List<CommandLineOption> getMissingOptions ()
   {
     ArrayList<CommandLineOption> result = new ArrayList<CommandLineOption> ();
     for (CommandLineOption option : mOptionSet)
     {
       if (! option.isSet () && option.isMandatory ()) result.add (option);
     }
     return result;
   }
 
   public String getShortOptionsMarker ()
   {
     return mShortOptionsMarker;
   }
 
   public void setShortOptionsMarker (String shortOptionsMarker)
   {
     if (shortOptionsMarker == null)
       throw new NullPointerException ("Short options marker is null.");
 
     if (mEvaluated) throw new IllegalStateException ("Arguments have already been evaluated.");
 
     mShortOptionsMarker = shortOptionsMarker;
   }
 
   public String getLongOptionsMarker ()
   {
     return mLongOptionsMarker;
   }
 
   public void setDescription (String description)
   {
     if (description == null) mDescription = "";
     mDescription = description;
   }
 
   public String getDescription ()
   {
     return mDescription;
   }
 
   public void setLongOptionsMarker (String longOptionsMarker)
   {
     if (longOptionsMarker == null) throw new NullPointerException ("Long options marker is null.");
 
     if (mEvaluated) throw new IllegalStateException ("Arguments have already been evaluated.");
 
     mLongOptionsMarker = longOptionsMarker;
   }
 }