Author: roxspring
Date: Fri Jun 3 18:09:22 2005
New Revision: 179921
URL: http://svn.apache.org/viewcvs?rev=179921&view=rev
Log:
Added CLI2 Overview documentation
Modified:
jakarta/commons/proper/cli/trunk/src/test/org/apache/commons/cli2/DocumentationTest.java
jakarta/commons/proper/cli/trunk/xdocs/manual/index.xml
Modified:
jakarta/commons/proper/cli/trunk/src/test/org/apache/commons/cli2/DocumentationTest.java
URL:
http://svn.apache.org/viewcvs/jakarta/commons/proper/cli/trunk/src/test/org/apache/commons/cli2/DocumentationTest.java?rev=179921&r1=179920&r2=179921&view=diff
==============================================================================
---
jakarta/commons/proper/cli/trunk/src/test/org/apache/commons/cli2/DocumentationTest.java
(original)
+++
jakarta/commons/proper/cli/trunk/src/test/org/apache/commons/cli2/DocumentationTest.java
Fri Jun 3 18:09:22 2005
@@ -27,6 +27,7 @@
import org.apache.commons.cli2.builder.DefaultOptionBuilder;
import org.apache.commons.cli2.builder.GroupBuilder;
import org.apache.commons.cli2.commandline.Parser;
+import org.apache.commons.cli2.option.DefaultOption;
import org.apache.commons.cli2.option.PropertyOption;
import org.apache.commons.cli2.util.HelpFormatter;
@@ -147,6 +148,81 @@
"Unexpected --bad-option while processing options",
uoe.getMessage());
}
+ }
+
+ public void testManualIntroduction() {
+
+ 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();
+
+ ///////////////////////////////////////////////////
+
+ try {
+ Group options = null;
+ HelpFormatter hf = new HelpFormatter();
+
+ Parser p = new Parser();
+ p.setGroup(options);
+ p.setHelpFormatter(hf);
+ p.setHelpTrigger("--help");
+ CommandLine cl = p.parseAndHelp(new String[]{});
+ if(cl==null) {
+ System.exit(-1);
+ }
+ } catch (IOException e) {
+ // TODO Auto-generated catch block
+ e.printStackTrace();
+ }
+
+ //////////////////////////////////////////////////
+
+ CommandLine cl = null;
+
+ // 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);
+ }
+
+
+
+
+ }
+
+ private void configureOutput(String path, boolean xml) {
+ // TODO Auto-generated method stub
+
}
public void testExampleAnt() throws IOException, OptionException {
Modified: jakarta/commons/proper/cli/trunk/xdocs/manual/index.xml
URL:
http://svn.apache.org/viewcvs/jakarta/commons/proper/cli/trunk/xdocs/manual/index.xml?rev=179921&r1=179920&r2=179921&view=diff
==============================================================================
--- jakarta/commons/proper/cli/trunk/xdocs/manual/index.xml (original)
+++ jakarta/commons/proper/cli/trunk/xdocs/manual/index.xml Fri Jun 3 18:09:22
2005
@@ -1,6 +1,6 @@
<?xml version="1.0"?>
<!--
- Copyright 2004 The Apache Software Foundation
+ Copyright 2004-2005 The Apache Software Foundation
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
@@ -15,29 +15,178 @@
limitations under the License.
-->
<document>
+
+ <properties>
+ <author email="commons-dev@jakarta.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();
- <properties>
- <author email="commons-dev@jakarta.apache.org">commons-dev</author>
- <title>CLI2 - Overview</title>
- </properties>
-
- <body>
- <section name="Overview">
- <p>TODO quick overview to the overview</p>
- <subsection name="Modelling the interface">
- <p>TODO terminology</p>
- <p>TODO basic options</p>
- <p>TODO option builders</p>
- </subsection>
- <subsection name="Parsing the command line">
- <p>TODO Parser</p>
- <p>TODO OptionException</p>
- <p>TODO HelpFormatter</p>
- </subsection>
- <subsection name="Querying the result">
- <p>TODO CommandLine</p>
- <p>TODO DefaultingCommandLine</p>
- </subsection>
- </section>
- </body>
+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. The HelpFormatter is discussed in detail
in the
+ <a href="utilities.html#HelpFormatter">Utilities</a>
section of the manual.
+ </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. The CommandLine interface and implementations
are discussed
+ further in the <a
href="commandlines.html">CommandLines</a> section of the
+ manual.
+ </p>
+ </subsection>
+ </section>
+ </body>
</document>
---------------------------------------------------------------------
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
