Updating site to be CLI1 specific
git-svn-id: https://svn.apache.org/repos/asf/commons/proper/cli/branches/cli-1.x@756341 13f79535-47bb-0310-9956-ffa450edef68
diff --git a/pom.xml b/pom.xml
index 12aa0af..e0a14cb 100644
--- a/pom.xml
+++ b/pom.xml
@@ -176,44 +176,71 @@
</build>
<reporting>
- <plugins>
- <plugin>
- <groupId>org.codehaus.mojo</groupId>
- <artifactId>findbugs-maven-plugin</artifactId>
- <version>1.2</version>
- <configuration>
- <threshold>Normal</threshold>
- <effort>Default</effort>
- </configuration>
- </plugin>
- <plugin>
- <groupId>org.apache.maven.plugins</groupId>
- <artifactId>maven-checkstyle-plugin</artifactId>
- <configuration>
- <configLocation>src/conf/checkstyle.xml</configLocation>
- </configuration>
- </plugin>
- <plugin>
- <groupId>org.apache.maven.plugins</groupId>
- <artifactId>maven-pmd-plugin</artifactId>
- </plugin>
- <plugin>
- <groupId>org.codehaus.mojo</groupId>
- <artifactId>cobertura-maven-plugin</artifactId>
- <version>2.2</version>
- </plugin>
- <plugin>
- <groupId>org.codehaus.mojo</groupId>
- <artifactId>clirr-maven-plugin</artifactId>
- <version>2.2.1</version>
- <configuration>
- <comparisonVersion>1.1</comparisonVersion>
- </configuration>
- </plugin>
- </plugins>
+ <plugins>
+ <plugin>
+ <groupId>org.apache.maven.plugins</groupId>
+ <artifactId>maven-javadoc-plugin</artifactId>
+ <configuration>
+ <linksource>true</linksource>
+ <links>
+ <link>http://java.sun.com/javase/6/docs/api</link>
+ </links>
+ </configuration>
+ </plugin>
+ <plugin>
+ <groupId>org.apache.maven.plugins</groupId>
+ <artifactId>maven-changes-plugin</artifactId>
+ <version>2.0</version>
+ <configuration>
+ <xmlPath>${basedir}/xdocs/changes.xml</xmlPath>
+ <issueLinkTemplate>%URL%/%ISSUE%</issueLinkTemplate>
+ </configuration>
+ <reportSets>
+ <reportSet>
+ <reports>
+ <report>changes-report</report>
+ </reports>
+ </reportSet>
+ </reportSets>
+ </plugin>
+ <plugin>
+ <groupId>org.apache.maven.plugins</groupId>
+ <artifactId>maven-checkstyle-plugin</artifactId>
+ <version>2.1</version>
+ <configuration>
+ <configLocation>src/conf/checkstyle.xml</configLocation>
+ <enableRulesSummary>false</enableRulesSummary>
+ </configuration>
+ </plugin>
+ <plugin>
+ <groupId>org.codehaus.mojo</groupId>
+ <artifactId>findbugs-maven-plugin</artifactId>
+ <version>1.2</version>
+ <configuration>
+ <threshold>Normal</threshold>
+ <effort>Default</effort>
+ </configuration>
+ </plugin>
+ <plugin>
+ <groupId>org.codehaus.mojo</groupId>
+ <artifactId>cobertura-maven-plugin</artifactId>
+ <version>2.2</version>
+ </plugin>
+ <plugin>
+ <groupId>org.codehaus.mojo</groupId>
+ <artifactId>clirr-maven-plugin</artifactId>
+ <version>2.2.1</version>
+ <configuration>
+ <comparisonVersion>1.1</comparisonVersion>
+ </configuration>
+ </plugin>
+ <plugin>
+ <groupId>org.apache.maven.plugins</groupId>
+ <artifactId>maven-pmd-plugin</artifactId>
+ </plugin>
+ </plugins>
</reporting>
-
<profiles>
<!-- Profile to let Gump choose the name of the jar file generated -->
<profile>
diff --git a/src/site/site.xml b/src/site/site.xml
index 74c6826..1eef929 100644
--- a/src/site/site.xml
+++ b/src/site/site.xml
@@ -32,21 +32,13 @@
<item name="Source Repository" href="/source-repository.html"/>
</menu>
- <menu name="CLI 1 User Guide">
+ <menu name="User Guide">
<item name="Getting started" href="/introduction.html"/>
<item name="Usage scenarios" href="/usage.html"/>
<item name="Option properties" href="/properties.html"/>
<item name="Javadoc (1.2)" href="api-release/index.html"/>
</menu>
- <menu name="CLI 2 User Guide (dev)">
- <item name="Overview" href="/manual/index.html"/>
- <item name="Examples" href="/examples/index.html"/>
- <item name="Options" href="/manual/options.html"/>
- <item name="Validators" href="/manual/validators.html"/>
- <item name="Javadoc (SVN latest)" href="apidocs/index.html"/>
- </menu>
-
</body>
</project>
diff --git a/xdocs/examples/ant.xml b/xdocs/examples/ant.xml
deleted file mode 100644
index 8be3bf5..0000000
--- a/xdocs/examples/ant.xml
+++ /dev/null
@@ -1,301 +0,0 @@
-<?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>Examples - ant</title>
- </properties>
-
- <body>
- <section name="ant">
- <p>
- This example works through modelling Apache Ant using CLI2, the
- example is based on Apache Ant version 1.6.1 compiled on February 12
- 2004.
- </p>
- <p>
- "Apache Ant is a Java-based build tool. In theory, it is kind of like
- Make, but without Make's wrinkles." - For more information please
- visit <a href="http://ant.apache.org/">http://ant.apache.org/</a>
- </p>
- <subsection name="Modelling">
- <p>
- To model the ant options we first need to create some Builders so that
- each of the option instances can be created:
- </p>
-<source>final DefaultOptionBuilder obuilder = new DefaultOptionBuilder();
-final ArgumentBuilder abuilder = new ArgumentBuilder();
-final GroupBuilder gbuilder = new GroupBuilder();</source>
- <p>
- For each option we create an Option instance that will model it, built
- using the Builder instances above:
- </p>
-<source>Option help =
- obuilder
- .withShortName("help")
- .withShortName("h")
- .withDescription("print this message")
- .create();
-Option projecthelp =
- obuilder
- .withShortName("projecthelp")
- .withShortName("p")
- .withDescription("print project help information")
- .create();
-Option version =
- obuilder
- .withShortName("version")
- .withDescription("print the version information and exit")
- .create();
-Option diagnostics =
- obuilder
- .withShortName("diagnostics")
- .withDescription("print information that might be helpful to diagnose or report problems.")
- .create();
-Option quiet =
- obuilder
- .withShortName("quiet")
- .withShortName("q")
- .withDescription("be extra quiet")
- .create();
-Option verbose =
- obuilder
- .withShortName("verbose")
- .withShortName("v")
- .withDescription("be extra verbose")
- .create();
-Option debug =
- obuilder
- .withShortName("debug")
- .withShortName("d")
- .withDescription("print debugging information")
- .create();
-Option emacs =
- obuilder
- .withShortName("emacs")
- .withShortName("e")
- .withDescription("produce logging information without adornments")
- .create();
-Option lib =
- obuilder
- .withShortName("lib")
- .withDescription("specifies a path to search for jars and classes")
- .withArgument(
- abuilder
- .withName("path")
- .withMinimum(1)
- .withMaximum(1)
- .create())
- .create();
-Option logfile =
- obuilder
- .withShortName("logfile")
- .withShortName("l")
- .withDescription("use given file for log")
- .withArgument(
- abuilder
- .withName("file")
- .withMinimum(1)
- .withMaximum(1)
- .create())
- .create();
-Option logger =
- obuilder
- .withShortName("logger")
- .withDescription("the class which is to perform logging")
- .withArgument(
- abuilder
- .withName("classname")
- .withMinimum(1)
- .withMaximum(1)
- .create())
- .create();
-Option listener =
- obuilder
- .withShortName("listener")
- .withDescription("add an instance of class as a project listener")
- .withArgument(
- abuilder
- .withName("classname")
- .withMinimum(1)
- .withMaximum(1)
- .create())
- .create();
-Option noinput =
- obuilder
- .withShortName("noinput")
- .withDescription("do not allow interactive input")
- .create();
-Option buildfile =
- obuilder
- .withShortName("buildfile")
- .withShortName("file")
- .withShortName("f")
- .withDescription("use given buildfile")
- .withArgument(
- abuilder
- .withName("file")
- .withMinimum(1)
- .withMaximum(1)
- .create())
- .create();
-Option property = new PropertyOption();
-Option propertyfile =
- obuilder
- .withShortName("propertyfile")
- .withDescription("load all properties from file with -D properties taking precedence")
- .withArgument(
- abuilder
- .withName("name")
- .withMinimum(1)
- .withMaximum(1)
- .create())
- .create();
-Option inputhandler =
- obuilder
- .withShortName("inputhandler")
- .withDescription("the class which will handle input requests")
- .withArgument(
- abuilder
- .withName("class")
- .withMinimum(1)
- .withMaximum(1)
- .create())
- .create();
-Option find =
- obuilder
- .withShortName("find")
- .withShortName("s")
- .withDescription("search for buildfile towards the root of the filesystem and use it")
- .withArgument(
- abuilder
- .withName("file")
- .withMinimum(1)
- .withMaximum(1)
- .create())
- .create();
-Option targets = abuilder.withName("target").create();</source>
- <p>
- We now create a Group instance consisting of all the above options:
- </p>
-<source>Group options =
- gbuilder
- .withName("options")
- .withOption(help)
- .withOption(projecthelp)
- .withOption(version)
- .withOption(diagnostics)
- .withOption(quiet)
- .withOption(verbose)
- .withOption(debug)
- .withOption(emacs)
- .withOption(lib)
- .withOption(logfile)
- .withOption(logger)
- .withOption(listener)
- .withOption(noinput)
- .withOption(buildfile)
- .withOption(property)
- .withOption(propertyfile)
- .withOption(inputhandler)
- .withOption(find)
- .withOption(targets)
- .create();</source>
- </subsection>
- <subsection name="Querying">
- <p>
- Once the model is built, a CommandLine needs to be parsed:
- </p>
-<source>Parser parser = new Parser();
-parser.setGroup(options);
-CommandLine cl = parser.parse(args);</source>
- <p>
- The CommandLine can be tested for the presence of options using the
- hasOption() methods which take either an option instance or a trigger
- value to lookup against:
- </p>
-<source>if(cl.hasOption(help)) {
- //displayHelp();
- return;
-}
-if(cl.hasOption("-version")) {
- //displayVersion();
- return;
-}</source>
- <p>
- For those options that have an argument, the argument needs to be
- extracted and processed:
- </p>
-<source>if(cl.hasOption(logfile)) {
- String file = (String)cl.getValue(logfile);
- //setLogFile(file);
-}</source>
- <p>
- Each target for ant to process could then be processed in order as
- specified:
- </p>
-<source>List targetList = cl.getValues(targets);
-for (Iterator i = targetList.iterator(); i.hasNext();) {
- String target = (String) i.next();
- //doTarget(target);
-}</source>
- </subsection>
- <subsection name="Helping">
- <p>
- To generate a help page for ant we first need to create a
- HelpFormatter and set some basic properties. The shell command is
- the command that the user would have typed to invoke the application,
- and the group is the group of options that compose the model.
- </p>
-<source>HelpFormatter hf = new HelpFormatter();
-hf.setShellCommand("ant");
-hf.setGroup(options);</source>
- <p>
- The first section of help will display the full usage string for the
- application, the appearence of this line can be adjusted using the
- HelpFormatter's fullUsageSettings property:
- </p>
-<source>hf.getFullUsageSettings().add(DisplaySetting.DISPLAY_GROUP_NAME);
-hf.getFullUsageSettings().add(DisplaySetting.DISPLAY_GROUP_ARGUMENT);
-hf.getFullUsageSettings().remove(DisplaySetting.DISPLAY_GROUP_EXPANDED);</source>
- <p>
- The main body of the help is based on a line or more of information
- about each option in the model. DisplaySettings can be used again to
- adjust which items are included in this display and which aren't. In
- this case, we don't want to display any groups as the top one is the
- only one present and can be inferred:
- </p>
-<source>hf.getDisplaySettings().remove(DisplaySetting.DISPLAY_GROUP_ARGUMENT);</source>
- <p>
- Each of the options identified by the displaySettings above has some
- usage information displayed, usually this will be a minimal set of
- DisplaySettings but these can be adjusted to get the desired effect:
- </p>
-<source>hf.getLineUsageSettings().add(DisplaySetting.DISPLAY_PROPERTY_OPTION);
-hf.getLineUsageSettings().add(DisplaySetting.DISPLAY_PARENT_ARGUMENT);
-hf.getLineUsageSettings().add(DisplaySetting.DISPLAY_ARGUMENT_BRACKETED);</source>
- <p>
- Finally, the help can be printed to System.out with a simple call to
- <code>print()</code>:
- </p>
-<source>hf.print();</source>
- </subsection>
- </section>
- </body>
-</document>
diff --git a/xdocs/examples/index.xml b/xdocs/examples/index.xml
deleted file mode 100644
index b3865e0..0000000
--- a/xdocs/examples/index.xml
+++ /dev/null
@@ -1,49 +0,0 @@
-<?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>Examples</title>
- </properties>
-
- <body>
- <section name="Overview">
- <p>
- The examples section aims to show how a variety of applications and
- tools could be modelled using CLI2. We make no claim that these tools
- use CLI2 in their implementation but simply use their interfaces to
- demonstrate commonly needed features. Some examples will make
- simplifications to keep the documentation consise.
- </p>
- <p>
- Many aspects of the API are touched upon but few are described in
- great detail. If more information is required then the reader is
- encouraged to review the API documentation and look at the unit tests
- for inspiration. Failing that, further advice and discussion can be
- found on the <code>user@commons.apache.org</code> mailing list.
- </p>
- </section>
-
- <section name="Examples">
- <ul>
- <li><a href="ant.html">ant</a></li>
- </ul>
- </section>
- </body>
-</document>
diff --git a/xdocs/index.xml b/xdocs/index.xml
index 215bc31..da69a04 100644
--- a/xdocs/index.xml
+++ b/xdocs/index.xml
@@ -61,16 +61,12 @@
</p>
</section>
- <section name="1.x vs 2.x?">
+ <section name="CLI 2?">
<p>Commons CLI 1.0 was formed from the merger of ideas and code from three different libraries -
Werken, Avalon and Optz. In dealing with the bugs and the feature requests a freshly designed and not
- backwards compatible CLI 2 was created, but never finished or released. Since then bugfix releases
- have been made for CLI 1.</p>
+ backwards compatible CLI 2 was created in 2004, but never finished or released. </p>
- <p>The current plan is to maintain the 1.x line until CLI 2 is officially released. The 2.x design is generally
- preferred and is in use, however there is no current activity to make a 2.0 release. To this end, the 1.2
- release is recommended to most users while the 2.x line is recommended for anyone interested in helping to get
- this better API released.</p>
+ <p>The current plan is to continue to maintain the 1.x line. The CLI2 work may be found in the Commons Sandbox. </p>
</section>
<section name="Documentation">
@@ -82,10 +78,10 @@
The Javadoc API documents are available online:
</p>
<ul>
+ <li><a href="apidocs/index.html">CLI 1.3-SNAPSHOT (latest SVN)</a></li>
<li><a href="api-release/index.html">CLI 1.2 (current release)</a></li>
<li><a href="api-1.1/index.html">CLI 1.1</a></li>
<li><a href="api-1.0/index.html">CLI 1.0</a></li>
- <li><a href="apidocs/index.html">CLI 2.0-SNAPSHOT (latest SVN)</a></li>
</ul>
<p>
The <a href="source-repository.html">Subversion repository</a> can be
@@ -114,78 +110,6 @@
<p>Issues may be reported via the <a href="issue-tracking.html">ASF JIRA</a>.</p>
</section>
-
- <!-- <p>
- CLI1 was formed by the merger of ideas and code from three different
- libraries and allows most simple interfaces to be modelled. CLI1
- became increasingly difficult to maintain and develop further and so
- CLI2 has been developed with the goals of clearer responsibilities and
- being more flexible. The intention is that CLI2 should be able to
- model a far greater selection of interfaces and do so more completely,
- validating as much as possible.
- </p>
- <p>
- The redesigned CLI2 is rooted in the <code>org.apache.commons.cli2</code>
- package and the distribution retains the <code>org.apache.commons.cli</code>
- package so that the upgrade doesn't break old code. The CLI1 package
- should be regarded as deprecated to encourage the transition to the
- more flexible CLI2 framework but minor bug fixes and patches may be
- accepted to ensure that CLI1 based applications continue to function as
- expected.
- </p>
- <p>
- The rest of the documentation is split into the following three sections:
- <ul>
- <li><a href="manual/index.html">CLI2</a> - a reference manual for version 2</li>
- <li><a href="introduction.html">CLI1</a> - documentation for version 1 </li>
- <li><a href="examples/index.html">Examples</a> - a selection of worked examples demonstrating CLI2 features</li>
- </ul>
- </p>
- <p>
- The latest version of this documentation is available on the web:
- <ul>
- <li><a href="http://commons.apache.org/cli/">http://commons.apache.org/cli/</a></li>
- <li>
- <a href="http://commons.apache.org/cli/commons-cli.pdf">http://commons.apache.org/cli/commons-cli.pdf</a>
- <a href="http://commons.apache.org/cli/commons-cli.pdf"><img border="0" src="images/pdf.gif"/></a>
- </li>
- </ul>
- </p>
- </section>
- <section name="Dependancies">
- <p>
- The generated list of <a href="dependencies.html">dependencies</a>
- lists the libraries needed to compile and test Commons CLI. To use
- the precompiled distribution none of these dependancies are strictly
- necessary. The following is a breakdown of what is required and when:
- </p>
- <table>
- <tr>
- <th>Library</th><th>Usage</th>
- </tr>
- <tr>
- <td>Java 1.2</td>
- <td>This is the minimum java level needed to use CLI2</td>
- </tr>
- <tr>
- <td>Java 1.4</td>
- <td>Needed if the PreferencesCommandLine is needed</td>
- </tr>
- <tr>
- <td>commons-lang</td>
- <td>Needed if the CLI1 package is being used</td>
- </tr>
- <tr>
- <td>jdepend</td>
- <td>Needed to build and test CLI2 only</td>
- </tr>
- <tr>
- <td>junit</td>
- <td>Needed to build and test CLI1 and CLI2</td>
- </tr>
- </table>
- </section>
- -->
</body>
</document>
diff --git a/xdocs/manual/index.xml b/xdocs/manual/index.xml
deleted file mode 100644
index b9c83f3..0000000
--- a/xdocs/manual/index.xml
+++ /dev/null
@@ -1,190 +0,0 @@
-<?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>
diff --git a/xdocs/manual/options.xml b/xdocs/manual/options.xml
deleted file mode 100644
index f61be97..0000000
--- a/xdocs/manual/options.xml
+++ /dev/null
@@ -1,377 +0,0 @@
-<?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 - Options</title>
- </properties>
-
- <body>
- <section name="Options">
- <subsection name="Option">
- <p>
- In CLI2 every element of the command line interface is modelled as an
- Option instance, and has the following readonly properties that are
- inherited by all other Option implementations:
- </p>
- <table>
- <tr>
- <th>Property</th><th>Type</th><th>Description</th>
- </tr>
- <tr>
- <td>id</td>
- <td>int</td>
- <td>
- Some people find it useful to give each option a unique identifer
- so that they can use the options within a java <code>switch</code>
- statement. This value is entirely optional and it is up to the
- user to ensure any uniqueness.
- </td>
- </tr>
- <tr>
- <td>preferredName</td>
- <td>String</td>
- <td>
- Every option has a preferred name that can be used for the minimal
- <code>toString()</code> implementation. Options can usually have
- many additional names too.
- </td>
- </tr>
- <tr>
- <td>required</td>
- <td>boolean</td>
- <td>
- True here indicates that the command line is invalid if this
- option doesn't appear on it.
- </td>
- </tr>
- </table>
- </subsection>
-
- <subsection name="Group">
- <source>-a|-b|-c|-d|-e</source>
- <p>
- Groups are possible the least intuitive form of Option since they
- actually represent a collection of other options. Most member Options
- can appear on a command line in any order with the exception of
- Arguments; they must appear in the given order as there is no other
- way to identify one from another. An additional restriction of the
- standard Group implementation is that only the final argument can have
- variable size (differing minimum and maximum).
- </p>
- <p>
- Groups inherit all the properties of Options.
- </p>
- <table>
- <tr>
- <th>Property</th><th>Type</th><th>Description</th>
- </tr>
- <tr>
- <td>minimum</td>
- <td>int</td>
- <td>
- The minimum number of member options that must be present on the
- command line for this group to be valid. Typically this will
- either be 0 where the group is optional or 1 to indicate at least
- one of them is needed. This value does not count anonymous
- options.
- </td>
- </tr>
- <tr>
- <td>maximum</td>
- <td>int</td>
- <td>
- The maximum number of options from this Group that can appear in a
- command line. This would typically be used if you wanted to
- create an exclusive group where a maximum of 1 member is allowed
- to appear. This value does not count anonymous options.
- </td>
- </tr>
- </table>
- </subsection>
-
- <subsection name="Argument">
- <source><arg1> [<arg2> ...]</source>
- <p>
- Arguments are used to pass in values from the command line, for
- example to pass in a list of files to be operated on. Arguments can
- appear in two different situations within an option model, the most
- frequently used situation is where the value found should be associated
- with a Parent option; in this situation the value is expected to
- immediately follow the Parent in the command line. The second
- scenario where Arguments are used is when they are added to a Group
- directly rather than being composed with a Parent first. These
- 'anonymous' arguments have nothing that identifies them on the
- command line other than the order in which they appear.
- </p>
- <p>
- Multiple values may be parsed by a single argument and the minimum
- and maximum attributes can used to control their validity,
- additionally a Validator may be used to identify whether individual
- values are valid. In some situations it can be useful to parse the
- supplied string into multiple values and so the initialSeparator and
- subsequentSeparator attributes can be used; assuming an
- initialSeparator of '=' and a subsequentSeparator of ',', the
- string '--file=a,b,c' would be split into a parent option '--file',
- and the values 'a', 'b' and 'c'.
- </p>
- <p>
- Arguments inherit all the properties of Options.
- </p>
- <table>
- <tr>
- <th>Property</th><th>Type</th><th>Description</th>
- </tr>
- <tr>
- <td>minimum</td>
- <td>int</td>
- <td>
- The minimum number of values that must be present for the
- Argument to be valid. The default of 0 implies that the argument
- is optional.
- </td>
- </tr>
- <tr>
- <td>maximum</td>
- <td>int</td>
- <td>
- The maximum number of values that can appear in a valid command
- line. A value less than minimum is not allowed.
- </td>
- </tr>
- <tr>
- <td>consumeRemaining</td>
- <td>String</td>
- <td>
- A string that can be used to avoid parsing of the remaining
- values as options. Typically '--' is used and allows file names
- to be used as values even though they look like options.
- </td>
- </tr>
- <tr>
- <td>initialSeparator</td>
- <td>char</td>
- <td>
- A character used to indicate the end of the parent option and the
- beginning of the values.
- </td>
- </tr>
- <tr>
- <td>subsequentSeparator</td>
- <td>char</td>
- <td>
- A character used to indicate the boundry between two values in a
- single string.
- </td>
- </tr>
- <tr>
- <td>defaultValue</td>
- <td>Object</td>
- <td>
- A value to be used when no other is supplied.
- </td>
- </tr>
- </table>
- </subsection>
-
- <subsection name="Parent">
- <source>--parent <arg> --child1|--child2</source>
- <p>
- Parent options allow an argument to be tied to some othe option,
- additionally a group of child options can also be added to the parent.
- The argument and child options are only valid in the presence of the
- parent option, must appear on the command line with the child options
- following the argument.
- </p>
- <p>
- Parents are not usable in themselves but DefaultOption, Switch and
- Command all inherit the parent features. Parents inherit the
- properties of Options.
- </p>
- <table>
- <tr>
- <th>Property</th><th>Type</th><th>Description</th>
- </tr>
- <tr>
- <td>argument</td>
- <td>Argument</td>
- <td>
- The Argument to delegate value processing to. This property is
- optional.
- </td>
- </tr>
- <tr>
- <td>children</td>
- <td>Group</td>
- <td>
- The Group to delegate child processing to. This property is
- optional.
- </td>
- </tr>
- </table>
- </subsection>
-
-
-
- <subsection name="DefaultOption">
- <source>--file (-f)</source>
- <p>
- The default option allows an option to exist with both long and short
- aliases. Ordinarily the short aliases would be a single character
- long and allow a series of options <code>-x -v -f</code> to be
- concatenated into a single element <code>-xvf</code> on the command
- line. This bursting of concatenated options can be turned off if
- necessary and the single character restriction can be ignored where
- bursting is not required.
- </p>
- <p>
- DefaultOptions inherit all the properties of Options and Parents.
- </p>
- <table>
- <tr>
- <th>Property</th><th>Type</th><th>Description</th>
- </tr>
- <tr>
- <td>shortName</td>
- <td>String</td>
- <td>
- The short name of the option. At least one short or long name is
- required.
- </td>
- </tr>
- <tr>
- <td>longName</td>
- <td>String</td>
- <td>
- The long name of the option. At least one short or long name is
- required.
- </td>
- </tr>
- <tr>
- <td>burstEnabled</td>
- <td>boolean</td>
- <td>
- Whether to allow this option to be concatenated with others.
- </td>
- </tr>
- </table>
- </subsection>
-
-
- <subsection name="Command">
- <source>update (up,upd)</source>
- <p>
- Commands are basically an option without an identifying prefix and
- are usually found in applications that implement a suite of tools
- within a single application. Any of a number of aliases can appear
- on the command line with idenentical meaning.
- </p>
- <p>
- Commands inherit all the properties of Options and Parents.
- </p>
- </subsection>
-
- <subsection name="Switch">
- <source>+display|-display</source>
- <p>
- Switches allow the user to turn a feature on or off. This becomes
- useful when the value would otherwise be taken from a different
- source and could change, for example the default value could be
- configurable by the user. A default switch value can be supplied in
- case no other source exists and the application writer has a
- preference.
- </p>
- <p>
- Switches inherit all the properties of Options and Parents.
- </p>
- <table>
- <tr>
- <th>Property</th><th>Type</th><th>Description</th>
- </tr>
- <tr>
- <td>defaultSwitch</td>
- <td>Boolean</td>
- <td>
- The value to be used if the option has not been configured. If
- not set the value <code>null</code> is used.
- </td>
- </tr>
- </table>
- </subsection>
-
- <subsection name="PropertyOption">
- <source>-Dproperty=value</source>
- <p>
- Property options allow arbitrary name value pairs to be passed in by
- the user. This style of option is often used to emulate the java
- <code>-D</code> option.
- </p>
- <p>
- PropertyOptions inherit the properties of Options.
- </p>
- <table>
- <tr>
- <th>Property</th><th>Type</th><th>Description</th>
- </tr>
- <tr>
- <td>optionString</td>
- <td>String</td>
- <td>
- The prefix for this option, defaults to <code>-D</code>.
- </td>
- </tr>
- </table>
- </subsection>
-
- <subsection name="SourceDestArgument">
-
-
-
- <source><src1> [<src2> ...] <dest></source>
- <p>
- Groups have the restriction that only the final argument can have
- variable size. Using the SourceDestArgument this rule can appear
- to be relaxed by shifting the variable size argument to an earlier
- position. A SourceDestArgument is implemented by composing two other
- options together. This option would typically be used when modelling
- commands like the unix cp command,
- </p>
- <table>
- <tr>
- <th>Property</th><th>Type</th><th>Description</th>
- </tr>
- <tr>
- <td>source</td>
- <td>Argument</td>
- <td>
- The variable size first argument.
- </td>
- </tr>
- <tr>
- <td>dest</td>
- <td>Argument</td>
- <td>
- The fixed size last argument.
- </td>
- </tr>
- </table>
- </subsection>
- </section>
- </body>
-</document>
diff --git a/xdocs/manual/validators.xml b/xdocs/manual/validators.xml
deleted file mode 100644
index b6e76f9..0000000
--- a/xdocs/manual/validators.xml
+++ /dev/null
@@ -1,202 +0,0 @@
-<?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 - Validators</title>
- </properties>
-
- <body>
- <section name="Validators">
- <p>
- CLI2 provides a mechanism to validate argument values. The <code>Validator</code>
- interface must be implemented to create an argument validator. This interface has
- a single method <code>validate(java.util.List values) throws InvalidArgumentException</code>.
- </p>
- <p>
- CLI2 has some standard validators included. They validate the following:
- </p>
- <ul>
- <li>Java class</li>
- <li>date</li>
- <li>enumeration</li>
- <li>file path</li>
- <li>number</li>
- <li>URL</li>
- </ul>
-
- <subsection name="ClassValidator">
- <p>
- The <code>ClassValidator</code> validates a value using three criteria:
- </p>
- <ol>
- <li>the value adheres to the Java Language Specification rules</li>
- <li>the class specified by the name is loadable</li>
- <li>the class specified by the name can be instantiated</li>
- </ol>
- <source>// 1.
-ClassValidator validator = new ClassValidator();
-// 2.
-validator.setLoadable(true);
-// 3.
-validator.setLoadable(true);</source>
- <p>
- TODO: add section about values being replaced with class instances
- </p>
- </subsection>
-
- <subsection name="DateValidator">
- <p>
- The <code>DateValidator</code> validates values against a
- <code>java.text.DateFormat</code>. There are three helper methods
- that create built-in validators.
- </p>
- <ol>
- <li><code>getDateInstance</code> returns a validator for the default
- date format for the default locale.
- </li>
- <li><code>getTimeInstance</code> returns a validator for the default
- time format for the default locale.
- </li>
- <li><code>getDateTimeInstance</code> returns a validator for the default
- date and time format for the default locale.
- </li>
- </ol>
- <p>
- A <code>DateValidator</code> can also be created by passing your
- a custom <code>DateFormat</code> into the constructor.
- </p>
- <source>DateFormat myFormat = DateFormat.getDateInstance( DateFormat.LONG, Locale.UK );
-DateValidator myValidator = new DateValidator( myFormat );</source>
- <p>
- In addition to basic format checking you can also check if the date/time specified
- is before/after a specific date/time. The lower bound is set using the
- <code>setMinimum( java.util.Date )</code>, and the upper bound is set using
- the <code>setMaximum( java.util.Date )</code>.
- </p>
- <p>
- TODO: add section about values being replaced with date instances
- </p>
- </subsection>
-
- <subsection name="EnumValidator">
- <p>
- The <code>EnumValidator</code> validates values against a list of
- allowed string values. The values that are allowed are specified in
- a <code>java.util.Set</code> and passed in to the constructor.
- </p>
- <source>Set enumSet = new TreeSet();
-enumSet.add("red");
-enumSet.add("green");
-enumSet.add("blue");
-
-EnumValidator validator = new EnumValidator( enumSet );</source>
- </subsection>
-
- <subsection name="FileValidator">
- <p>
- The <code>FileValidator</code> validates that values represent
- existing files. You can also specify a combination of the
- following additional criteria:
- </p>
- <ol>
- <li>value is a file</li>
- <li>value is a directory</li>
- <li>the file is writable</li>
- <li>the file is readable</li>
- <li>the file is hidden</li>
- </ol>
- <p>
- Each of the criteria listed here are specified using the appropriate
- setter.
- </p>
- <p>
- There are three helper methods to create validators:
- </p>
- <ol>
- <li><code>getExistingInstance</code> returns a validator that ensures
- a value represents an existing file.
- </li>
- <li><code>getExistingFileInstance</code> returns a validator that ensures
- a value represents an existing file that is not a directory.
- </li>
- <li><code>getExistingDirectoryInstance</code> returns a validator that ensures
- a value represents an existing file this is a directory.
- </li>
- </ol>
- <source>// validate that the value represents a file that exists
-FileValidator validator = FileValidator.getExistingInstance();
-
-// ensure it's not a hidden file
-validator.setHidden( false );
-
-// ensure it's a writable file
-validator.setWritable( true );</source>
-
- </subsection>
-
- <subsection name="NumberValidator">
- <p>
- The <code>NumberValidator</code> validates that values adhere to
- certain rules like the following:
- </p>
- <ol>
- <li><code>getCurrencyInstance</code> returns a validator for the default
- currency format for the default locale.
- </li>
- <li><code>getPercentInstance</code> returns a validator for the default
- percent format for the default locale.
- </li>
- <li><code>getIntegerInstance</code> returns a validator for the default
- integer format for the default locale.
- </li>
- <li><code>getNumberInstance</code> returns a validator for the default
- number format for the default locale.
- </li>
- </ol>
- <p>
- A <code>NumberValidator</code> can also be created by passing your
- a custom <code>NumberFormat</code> into the constructor.
- </p>
- <source>NumberFormat myFormat = NumberFormat.getCurrencyInstance( Locale.UK );
-NumberValidator myValidator = new NumberValidator( myFormat );</source>
- <p>
- In addition to basic format checking you can also check if the number specified
- is less than or greater than a specific number. The lower bound is set using
- the <code>setMinimum( Number )</code>, and the upper bound is set using
- the <code>setMaximum( Number )</code>.
- </p>
- </subsection>
-
- <subsection name="UrlValidator">
- <p>
- A <code>UrlValidator</code> validates that values are URLs and if you
- choose it will also validate the protocol is of the type you have
- specified.
- </p>
- <source>UrlValidator validator = new UrlValidator();
-
-// only accept https URLs
-validator.setProtocol("https");</source>
-
- </subsection>
-
- </section>
- </body>
-</document>
