xdocs/manual/index.xml - commons-cli - Git at Google

 <?xml version="1.0"?>
 <!--
  Licensed to the Apache Software Foundation (ASF) under one or more
  contributor license agreements.  See the NOTICE file distributed with
  this work for additional information regarding copyright ownership.
  The ASF licenses this file to You under the Apache License, Version 2.0
  (the "License"); you may not use this file except in compliance with
  the License.  You may obtain a copy of the License at

      http://www.apache.org/licenses/LICENSE-2.0

  Unless required by applicable law or agreed to in writing, software
  distributed under the License is distributed on an "AS IS" BASIS,
  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  See the License for the specific language governing permissions and
  limitations under the License.
 -->
 <document>

     <properties>
         <author email="dev@commons.apache.org">commons-dev</author>
         <title>CLI2 - Overview</title>
     </properties>

     <body>
         <section name="Overview">
             <p>
                 CLI Breaks down command line processing into three distinct phases, the
                 first of which is to create a model of the command line you wish to process. The
                 second phase is arguably the most important as it involves processing the
                 command line arguments of the application according to the model created.
                 Finally the parsed command line is available to be queried by the
                 application proper.  The phases are discussed in more detail below.
             </p>
             <subsection name="Modelling the interface">
                 <p>
                     In CLI2 a command line is modelled as a Group composed of many Options.
                     There are a number different Option implementations available to be
                     used including DefaultOption, Switch and Command which may all have an
                     Argument and/or a Group of child options associated with them. An
                     example of where this parental relationship could be used is where you
                     need to allow for the following scenario where one option
                     only makes sense within the context of another:
                 </p>
                 <p><code>myapp --output path/to/file --xml</code></p>
                 <p>
                     Typically this command line would be modelled as a DefaultOption
                     (<code>--output</code>) with an Argument (to capture
                     <code>path/to/file</code>) and a Group of children consisting of a
                     DefaultOption (<code>--xml</code>) since the format only applies if the
                     output is specified
                 </p>
                 <p>
                     The various Option implementations provided need careful configuration
                     and constructors take a complex set of arguments.  To ease the construction
                     of these options *Builder classes (e.g. DefaultOptionBuilder, GroupBuilder
                     and ArgumentBuilder) have been supplied following the
                     <a href="http://c2.com/cgi/wiki?BuilderPattern">Builder Pattern</a>
                     which essentially involves using the DefaultOptionBuilder class to create
                     instances of DefaultOption using descriptive method calls instead of
                     anonymous arguments to a constructor.  The following example demonstrates how
                     the command line shown above could be modelled in code:
                 </p>
                 <source>
 DefaultOptionBuilder oBuilder = new DefaultOptionBuilder();
 ArgumentBuilder aBuilder = new ArgumentBuilder();
 GroupBuilder gBuilder = new GroupBuilder();

 DefaultOption xmlOption =
     oBuilder
         .withLongName("xml")
         .withDescription("Output using xml format")
         .create();

 Argument pathArgument =
     aBuilder
         .withName("path")
         .withMinimum(1)
         .withMaximum(1)
         .create();

 Group outputChildren =
     gBuilder
         .withOption(xmlOption)
         .create();

 Option outputOption =
     oBuilder
         .withLongName("output")
         .withDescription("Outputs to a file")
         .withArgument(pathArgument)
         .withChildren(outputChildren)
         .create();
                 </source>
                 <p>
                     The <a href="options.html">Options</a> and
                     <a href="builders.html">Builders</a> sections of the manual discuss these
                     features in greater detail.
                 </p>
                 <p>
                     Once all the options have been composed into a Group modelling the complete
                     option model then we are ready to parse a command line.
                 </p>
             </subsection>
             <subsection name="Parsing the command line">
                 <p>
                     The Parser class can be used to parse an array of arguments against the
                     option model into a CommandLine.  The parsing is driven by the
                     <code>parse(String[])</code> method which delegates to the option model to do
                     the actual parsing, with each Option implementation providing its own parsing
                     logic.  The <code>parseAndHelp(String[])</code> method attempts to simplify
                     the use of the former method by automatically handling any <code>--help</code>
                     options and displaying error messages where appropriate.
                 </p>
                 <p>
                     The HelpFormatter class is designed to allow the option model to be described
                     to the user in a manner typical of command line applications.  The
                     HelpFormatter is designed with flexibility in mind so it should be possible to
                     control exactly which structures are described to the user and what level of
                     detail to use.
                 </p>
                 <p>
                     Any errors that occur while parsing result in an OptionException being thrown
                     which attempt to provide a meaningful message describing the problem to the
                     user.  Parser's <code>parseAndHelp(String[])</code> method catches any
                     OptionException and uses the HelpFormatter to display to the user:
                 </p>
                 <source>
 // configure the options
 Group options = ...;

 // configure a HelpFormatter
 HelpFormatter hf = new HelpFormatter();

 // configure a parser
 Parser p = new Parser();
 p.setGroup(options);
 p.setHelpFormatter(hf);
 p.setHelpTrigger("--help");
 CommandLine cl = p.parseAndHelp(new String[]{});

 // abort application if no CommandLine was parsed
 if(cl==null) {
     System.exit(-1);
 }
                 </source>

                 <p>
                     Assuming that OptionExceptions have been averted then the next step is to have
                     the application query the resulting CommandLine instance.
                 </p>
             </subsection>
             <subsection name="Querying the result">
                 <p>
                     The CommandLine interface provides lots of ways to look up information either
                     by Option instance or by a String representing any of the forms valid on the
                     command line.  For example if an option is configured with multiple names
                     (e.g. <code>-?</code>, <code>-h</code>, <code>--help</code>) then any of the
                     those strings can be used to look up the value irrespective of which form
                     appeared on the command line.
                 </p>
                 <p>
                     The <code>hasOption()</code> family of methods can be used to simply test for
                     the presence of options, while the <code>getValues()</code> family of methods
                     can be used to retrieve the values associated with Arguments.  The status of
                     any Switch options can be detected through the use of <code>getSwitch()</code>
                     methods which will return a Boolean if set or null otherwise:
                 </p>
                 <source>
 // if we have --output option
 if(cl.hasOption("--output")) {
     // grab the path
     String path = (String)cl.getValue("--output");
     // grab the format
     boolean xml = cl.hasOption("--xml");
     // configure the application's output
     configureOutput(path,xml);
 }
                 </source>
                 <p>
                     To enable complex CommandLine configurations alternative implementations are
                     provided that can wrap a Properties or Preferences instance as a CommandLine.
                     These can then be combined with the DefaultingCommandLine and the parsed
                     CommandLine to provide a variety of different defaulting and overriding
                     scenarios.
                 </p>
             </subsection>
         </section>
     </body>
 </document>
	<?xml version="1.0"?>
	<!--
	Licensed to the Apache Software Foundation (ASF) under one or more
	contributor license agreements. See the NOTICE file distributed with
	this work for additional information regarding copyright ownership.
	The ASF licenses this file to You under the Apache License, Version 2.0
	(the "License"); you may not use this file except in compliance with
	the License. You may obtain a copy of the License at

	http://www.apache.org/licenses/LICENSE-2.0

	Unless required by applicable law or agreed to in writing, software
	distributed under the License is distributed on an "AS IS" BASIS,
	WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
	See the License for the specific language governing permissions and
	limitations under the License.
	-->
	<document>

	<properties>
	<author email="dev@commons.apache.org">commons-dev</author>
	<title>CLI2 - Overview</title>
	</properties>

	<body>
	<section name="Overview">
	<p>
	CLI Breaks down command line processing into three distinct phases, the
	first of which is to create a model of the command line you wish to process. The
	second phase is arguably the most important as it involves processing the
	command line arguments of the application according to the model created.
	Finally the parsed command line is available to be queried by the
	application proper. The phases are discussed in more detail below.
	</p>
	<subsection name="Modelling the interface">
	<p>
	In CLI2 a command line is modelled as a Group composed of many Options.
	There are a number different Option implementations available to be
	used including DefaultOption, Switch and Command which may all have an
	Argument and/or a Group of child options associated with them. An
	example of where this parental relationship could be used is where you
	need to allow for the following scenario where one option
	only makes sense within the context of another:
	</p>
	<p><code>myapp --output path/to/file --xml</code></p>
	<p>
	Typically this command line would be modelled as a DefaultOption
	(<code>--output</code>) with an Argument (to capture
	<code>path/to/file</code>) and a Group of children consisting of a
	DefaultOption (<code>--xml</code>) since the format only applies if the
	output is specified
	</p>
	<p>
	The various Option implementations provided need careful configuration
	and constructors take a complex set of arguments. To ease the construction
	of these options *Builder classes (e.g. DefaultOptionBuilder, GroupBuilder
	and ArgumentBuilder) have been supplied following the
	<a href="http://c2.com/cgi/wiki?BuilderPattern">Builder Pattern</a>
	which essentially involves using the DefaultOptionBuilder class to create
	instances of DefaultOption using descriptive method calls instead of
	anonymous arguments to a constructor. The following example demonstrates how
	the command line shown above could be modelled in code:
	</p>
	<source>
	DefaultOptionBuilder oBuilder = new DefaultOptionBuilder();
	ArgumentBuilder aBuilder = new ArgumentBuilder();
	GroupBuilder gBuilder = new GroupBuilder();

	DefaultOption xmlOption =
	oBuilder
	.withLongName("xml")
	.withDescription("Output using xml format")
	.create();

	Argument pathArgument =
	aBuilder
	.withName("path")
	.withMinimum(1)
	.withMaximum(1)
	.create();

	Group outputChildren =
	gBuilder
	.withOption(xmlOption)
	.create();

	Option outputOption =
	oBuilder
	.withLongName("output")
	.withDescription("Outputs to a file")
	.withArgument(pathArgument)
	.withChildren(outputChildren)
	.create();
	</source>
	<p>
	The <a href="options.html">Options</a> and
	<a href="builders.html">Builders</a> sections of the manual discuss these
	features in greater detail.
	</p>
	<p>
	Once all the options have been composed into a Group modelling the complete
	option model then we are ready to parse a command line.
	</p>
	</subsection>
	<subsection name="Parsing the command line">
	<p>
	The Parser class can be used to parse an array of arguments against the
	option model into a CommandLine. The parsing is driven by the
	<code>parse(String[])</code> method which delegates to the option model to do
	the actual parsing, with each Option implementation providing its own parsing
	logic. The <code>parseAndHelp(String[])</code> method attempts to simplify
	the use of the former method by automatically handling any <code>--help</code>
	options and displaying error messages where appropriate.
	</p>
	<p>
	The HelpFormatter class is designed to allow the option model to be described
	to the user in a manner typical of command line applications. The
	HelpFormatter is designed with flexibility in mind so it should be possible to
	control exactly which structures are described to the user and what level of
	detail to use.
	</p>
	<p>
	Any errors that occur while parsing result in an OptionException being thrown
	which attempt to provide a meaningful message describing the problem to the
	user. Parser's <code>parseAndHelp(String[])</code> method catches any
	OptionException and uses the HelpFormatter to display to the user:
	</p>
	<source>
	// configure the options
	Group options = ...;

	// configure a HelpFormatter
	HelpFormatter hf = new HelpFormatter();

	// configure a parser
	Parser p = new Parser();
	p.setGroup(options);
	p.setHelpFormatter(hf);
	p.setHelpTrigger("--help");
	CommandLine cl = p.parseAndHelp(new String[]{});

	// abort application if no CommandLine was parsed
	if(cl==null) {
	System.exit(-1);
	}
	</source>

	<p>
	Assuming that OptionExceptions have been averted then the next step is to have
	the application query the resulting CommandLine instance.
	</p>
	</subsection>
	<subsection name="Querying the result">
	<p>
	The CommandLine interface provides lots of ways to look up information either
	by Option instance or by a String representing any of the forms valid on the
	command line. For example if an option is configured with multiple names
	(e.g. <code>-?</code>, <code>-h</code>, <code>--help</code>) then any of the
	those strings can be used to look up the value irrespective of which form
	appeared on the command line.
	</p>
	<p>
	The <code>hasOption()</code> family of methods can be used to simply test for
	the presence of options, while the <code>getValues()</code> family of methods
	can be used to retrieve the values associated with Arguments. The status of
	any Switch options can be detected through the use of <code>getSwitch()</code>
	methods which will return a Boolean if set or null otherwise:
	</p>
	<source>
	// if we have --output option
	if(cl.hasOption("--output")) {
	// grab the path
	String path = (String)cl.getValue("--output");
	// grab the format
	boolean xml = cl.hasOption("--xml");
	// configure the application's output
	configureOutput(path,xml);
	}
	</source>
	<p>
	To enable complex CommandLine configurations alternative implementations are
	provided that can wrap a Properties or Preferences instance as a CommandLine.
	These can then be combined with the DefaultingCommandLine and the parsed
	CommandLine to provide a variety of different defaulting and overriding
	scenarios.
	</p>
	</subsection>
	</section>
	</body>
	</document>