/*
VisAD system for interactive analysis and visualization of numerical
data.  Copyright (C) 1996 - 2017 Bill Hibbard, Curtis Rueden, Tom
Rink, Dave Glowacki, Steve Emmerson, Tom Whittaker, Don Murray, and
Tommy Jasmin.

This library is free software; you can redistribute it and/or
modify it under the terms of the GNU Library General Public
License as published by the Free Software Foundation; either
version 2 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
Library General Public License for more details.

You should have received a copy of the GNU Library 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 visad.util;

public interface CmdlineConsumer
{
  /**
   * Method used to initialize any instance variables which may be
   * changed by a cmdline option.

   * 

   * This is needed when arguments are processed inside the
   * constructor.  If the first line in the constructor in a class
   * which extends this class is super(args),
   * {@link visad.util.CmdlineParser CmdlineParser} will be run
   * before any instance variables for the extending
   * class are initialized.

   * 

   * To ensure all instance variables are properly initialized,
   * place the initialization code in the initializeArgs() method.
   */
  void initializeArgs();

  /**
   * Handle subclass-specific command line options and their arguments.

   * 

   * If -abc -d efg -h -1 -i is specified, this
   * method will be called a maximum of 5 times:

   * 
checkOption(mainName, 'a', "bc");
   * 
checkOption(mainName, 'd', "efg");
   * 
checkOption(mainName, 'h', "-1");
   * 
checkOption(mainName, '1', "-i");
   * 
checkOption(mainName, 'i', null);
   * 
   * 

   * Note that either of the last two method calls may not
   * happen if the preceeding method call claims to have used
   * the following argument (by returning 2.

   * 

   * For example,
   * if the third call (where ch is set to 'h')
   * returns 0 or 1, the next call will contain
   * '1' and "-i".  If, however, the third call
   * returns 2, the next call will contain 'i'
   * and null.
   *
   * @param mainName The name of the main class (useful for
   *                 error messages.)
   * @param ch Option character.  If -a is specified
   *           on the command line, 'a' would be passed to
   *           this method.)
   * @param arg The argument associated with this option.
   *
   * @return less than 0 to indicate an error

   *         0 to indicate that this option is not used by this
   *         class

   *         1 to indicate that only the option was used

   *         2 or greater to indicate that both the option and the
   *         argument were used
   */
  int checkOption(String mainName, char ch, String arg);

  /**
   * A short string included in the usage message to indicate
   * valid options.  An example might be "[-t type]".
   *
   * @return A very terse description string.
   */
  String optionUsage();

  /**
   * Handle subclass-specific command line options and their arguments.
   *
   * @param mainName The name of the main class (useful for
   *                 error messages.)
   * @param thisArg The index of the current keyword.
   * @param args The full list of arguments.
   *
   * @return less than 0 to indicate an error

   *         0 to indicate that this argument is not used by this
   *         class

   *         1 or more to indicate the number of arguments used

   */
  int checkKeyword(String mainName, int thisArg, String[] args);

  /**
   * A short string included in the usage message to indicate
   * valid keywords.

   * 

   * An example might be "[username] [password]".
   *
   * @return A very terse description string.
   */
  String keywordUsage();

  /**
   * Validate arguments after argument parsing has finished.

   * 

   * This is useful for verifying that all required keywords and
   * options have been specified, that options don't conflict
   * with one another, etc.
   *
   * @param mainName The name of the main class (useful for
   *                 error messages.)
   *
   * @return true if everything is correct, false
   *         if there is a problem.
   */
  boolean finalizeArgs(String mainName);
}