src/java/org/apache/commons/cli/avalon/package.html - commons-cli - Git at Google

 <html>
     <head>
         <title>Package Documentation for org.apache.commons.cli.avalon Package</title>
     </head>
     <body bgcolor="white">
         Utility code for parsing command-line options.
        <br><br>
 <p style="font-weight:bold">
 These classes were originally in the Avalon project in the package org.apache.avalon.excalibur.cli
 </p>

         <h3>Introduction</h3>
         <p>The utilities in <code>org.apache.commons.cli.avalon</code> assist
         you in parsing command line options during startup time. It allows you
         to associate a short option and a long option to the same command, and
         then test for it in a switch statement.</p>
         <a name="doc.Usage"></a>
         <h3>Usage Example</h3>
         <pre>
 import java.util.List;

 import org.apache.commons.cli.avalon.CLArgsParser;
 import org.apache.commons.cli.avalon.CLOption;
 import org.apache.commons.cli.avalon.CLOptionDescriptor;
 import org.apache.commons.cli.avalon.CLUtil;

 /**
 * Demonstrates the excalibur command-line parsing utility.
 *
 */
 public class CLDemo {
     // Define our short one-letter option identifiers.
     protected static final int HELP_OPT = 'h';
     protected static final int VERSION_OPT = 'v';
     protected static final int MSG_OPT = 'm';

     /**
      *  Define the understood options. Each CLOptionDescriptor contains:
      * - The "long" version of the option. Eg, "help" means that "--help" will
      * be recognised.
      * - The option flags, governing the option's argument(s).
      * - The "short" version of the option. Eg, 'h' means that "-h" will be
      * recognised.
      * - A description of the option.
      */
     protected static final CLOptionDescriptor [] options = new CLOptionDescriptor [] {
         new CLOptionDescriptor("help",
                 CLOptionDescriptor.ARGUMENT_DISALLOWED,
                 HELP_OPT,
                 "print this message and exit"),
         new CLOptionDescriptor("version",
                 CLOptionDescriptor.ARGUMENT_DISALLOWED,
                 VERSION_OPT,
                 "print the version information and exit"),
         new CLOptionDescriptor("msg",
                 CLOptionDescriptor.ARGUMENT_REQUIRED,
                 MSG_OPT,
                 "the message to print"),
     };

     public static void main(String args[]) {
         // Parse the arguments
         CLArgsParser parser = new CLArgsParser(args, options);

         if( null != parser.getErrorString() ) {
            System.err.println( "Error: " + parser.getErrorString() );
            return;
         }

         // Get a list of parsed options
         List clOptions = parser.getArguments();
         int size = clOptions.size();

         for (int i = 0; i < size; i++) {
             CLOption option = (CLOption) clOptions.get(i);

             switch (option.getId()) {
                 case CLOption.TEXT_ARGUMENT:
                     System.out.println("Unknown arg: "+option.getArgument());
                     break;

                 case HELP_OPT:
                     printUsage();
                     break;

                 case VERSION_OPT:
                     printVersion();
                     break;


                 case MSG_OPT:
                     System.out.println(option.getArgument());
                     break;
             }
         }
     }

     private static void printVersion() {
         System.out.println("1.0");
         System.exit(0);
     }

     private static void printUsage() {
         String lSep = System.getProperty("line.separator");
         StringBuffer msg = new StringBuffer();
         msg.append("------------------------------------------------------------------------ ").append(lSep);
         msg.append("Excalibur command-line arg parser demo").append(lSep);
         msg.append("Usage: java "+CLDemo.class.getName()+" [options]").append(lSep).append(lSep);
         msg.append("Options: ").append(lSep);
         msg.append(CLUtil.describeOptions(CLDemo.options).toString());
         System.out.println(msg.toString());
         System.exit(0);
     }
 }
 </pre>

         <h3>Parsing Rules</h3>
                 <p>
                 The command line is parsed according to the following rules. There are
                 two forms of options in this package, the Long form and the Short form.
                 The long form of an option is preceded by the '--' characters while the
                 short form is preceded by a single '-'. Some example options would be;
                 "--an-option", "-a", "--day", "-s -f -a".
                 </p>
                 <p>
                 In the tradition of UNIX programs, the short form of an option can occur
                 immediately after another short form option. So if 'a', 'b' and 'c' are
                 short forms of options that take no parameters then the following
                 command lines are equivalent: "-abc", "-a -bc", "-a -b -c", "-ab -c", etc.
                 </p>
                 <p>
                 Options can also accept arguments if specified. You can specify that an
                 option requires an argument in which the text immediately following the
                 option will be considered to be an argument to the option. So if 'a' was an
                 option that required an argument then the following would be equivalent;
                 "-abc", "-a bc" (namely the option 'a' with argument 'bc').
                 </p>
                 <p>
                 Options can also specify optional arguments. In this case if there is any
                 text immediately following the option character then it is considered an
                 argument.  Otherwise, the option has no arguments. For example if 'a' was an
                 option that required an optional argument then "-abc" is an option 'a' with
                 argument "bc" while "-a bc" is an option 'a' with no argument, followed by
                 the text "bc". </p>
                 <p>It is also possible to place an '=' sign between the option
                 and its argument. So if we assume that a is an option that
                 requires an argument then the following are equivalent;
                 "-a=bc" and "-abc".
                 </p>
                 <p>
                 In the case of a long option with an optional argument, the '=' sign is required.
                 For example. --optarg=1, not --optarg 1.
                 </p>
                 <p>
                 In some cases it is also necessary to disable command line parsing so that you
                 can pass a text argument to the program that starts with a '-' character. To do
                 this insert the sequence '--' onto the command line with no text immediately
                 following it. This will disable processing for the rest of the command line.
                 The '--' characters will not be passed to the user program. For instance the
                 line "-- -b" would result in the program being passed the
                 text "-b" (ie. not as an option).
                 </p>
 </body>
 </html>
	<html>
	<head>
	<title>Package Documentation for org.apache.commons.cli.avalon Package</title>
	</head>
	<body bgcolor="white">
	Utility code for parsing command-line options.
	<br><br>
	<p style="font-weight:bold">
	These classes were originally in the Avalon project in the package org.apache.avalon.excalibur.cli
	</p>

	<h3>Introduction</h3>
	<p>The utilities in <code>org.apache.commons.cli.avalon</code> assist
	you in parsing command line options during startup time. It allows you
	to associate a short option and a long option to the same command, and
	then test for it in a switch statement.</p>
	<a name="doc.Usage"></a>
	<h3>Usage Example</h3>
	<pre>
	import java.util.List;

	import org.apache.commons.cli.avalon.CLArgsParser;
	import org.apache.commons.cli.avalon.CLOption;
	import org.apache.commons.cli.avalon.CLOptionDescriptor;
	import org.apache.commons.cli.avalon.CLUtil;

	/**
	* Demonstrates the excalibur command-line parsing utility.
	*
	*/
	public class CLDemo {
	// Define our short one-letter option identifiers.
	protected static final int HELP_OPT = 'h';
	protected static final int VERSION_OPT = 'v';
	protected static final int MSG_OPT = 'm';

	/**
	* Define the understood options. Each CLOptionDescriptor contains:
	* - The "long" version of the option. Eg, "help" means that "--help" will
	* be recognised.
	* - The option flags, governing the option's argument(s).
	* - The "short" version of the option. Eg, 'h' means that "-h" will be
	* recognised.
	* - A description of the option.
	*/
	protected static final CLOptionDescriptor [] options = new CLOptionDescriptor [] {
	new CLOptionDescriptor("help",
	CLOptionDescriptor.ARGUMENT_DISALLOWED,
	HELP_OPT,
	"print this message and exit"),
	new CLOptionDescriptor("version",
	CLOptionDescriptor.ARGUMENT_DISALLOWED,
	VERSION_OPT,
	"print the version information and exit"),
	new CLOptionDescriptor("msg",
	CLOptionDescriptor.ARGUMENT_REQUIRED,
	MSG_OPT,
	"the message to print"),
	};

	public static void main(String args[]) {
	// Parse the arguments
	CLArgsParser parser = new CLArgsParser(args, options);

	if( null != parser.getErrorString() ) {
	System.err.println( "Error: " + parser.getErrorString() );
	return;
	}

	// Get a list of parsed options
	List clOptions = parser.getArguments();
	int size = clOptions.size();

	for (int i = 0; i < size; i++) {
	CLOption option = (CLOption) clOptions.get(i);

	switch (option.getId()) {
	case CLOption.TEXT_ARGUMENT:
	System.out.println("Unknown arg: "+option.getArgument());
	break;

	case HELP_OPT:
	printUsage();
	break;

	case VERSION_OPT:
	printVersion();
	break;


	case MSG_OPT:
	System.out.println(option.getArgument());
	break;
	}
	}
	}

	private static void printVersion() {
	System.out.println("1.0");
	System.exit(0);
	}

	private static void printUsage() {
	String lSep = System.getProperty("line.separator");
	StringBuffer msg = new StringBuffer();
	msg.append("------------------------------------------------------------------------ ").append(lSep);
	msg.append("Excalibur command-line arg parser demo").append(lSep);
	msg.append("Usage: java "+CLDemo.class.getName()+" [options]").append(lSep).append(lSep);
	msg.append("Options: ").append(lSep);
	msg.append(CLUtil.describeOptions(CLDemo.options).toString());
	System.out.println(msg.toString());
	System.exit(0);
	}
	}
	</pre>

	<h3>Parsing Rules</h3>
	<p>
	The command line is parsed according to the following rules. There are
	two forms of options in this package, the Long form and the Short form.
	The long form of an option is preceded by the '--' characters while the
	short form is preceded by a single '-'. Some example options would be;
	"--an-option", "-a", "--day", "-s -f -a".
	</p>
	<p>
	In the tradition of UNIX programs, the short form of an option can occur
	immediately after another short form option. So if 'a', 'b' and 'c' are
	short forms of options that take no parameters then the following
	command lines are equivalent: "-abc", "-a -bc", "-a -b -c", "-ab -c", etc.
	</p>
	<p>
	Options can also accept arguments if specified. You can specify that an
	option requires an argument in which the text immediately following the
	option will be considered to be an argument to the option. So if 'a' was an
	option that required an argument then the following would be equivalent;
	"-abc", "-a bc" (namely the option 'a' with argument 'bc').
	</p>
	<p>
	Options can also specify optional arguments. In this case if there is any
	text immediately following the option character then it is considered an
	argument. Otherwise, the option has no arguments. For example if 'a' was an
	option that required an optional argument then "-abc" is an option 'a' with
	argument "bc" while "-a bc" is an option 'a' with no argument, followed by
	the text "bc". </p>
	<p>It is also possible to place an '=' sign between the option
	and its argument. So if we assume that a is an option that
	requires an argument then the following are equivalent;
	"-a=bc" and "-abc".
	</p>
	<p>
	In the case of a long option with an optional argument, the '=' sign is required.
	For example. --optarg=1, not --optarg 1.
	</p>
	<p>
	In some cases it is also necessary to disable command line parsing so that you
	can pass a text argument to the program that starts with a '-' character. To do
	this insert the sequence '--' onto the command line with no text immediately
	following it. This will disable processing for the rest of the command line.
	The '--' characters will not be passed to the user program. For instance the
	line "-- -b" would result in the program being passed the
	text "-b" (ie. not as an option).
	</p>
	</body>
	</html>