commons-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From roxspr...@apache.org
Subject svn commit: r179921 - in /jakarta/commons/proper/cli/trunk: src/test/org/apache/commons/cli2/DocumentationTest.java xdocs/manual/index.xml
Date Sat, 04 Jun 2005 01:09:23 GMT
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: commons-dev-unsubscribe@jakarta.apache.org
For additional commands, e-mail: commons-dev-help@jakarta.apache.org


Mime
View raw message