commons-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From roxspr...@apache.org
Subject cvs commit: jakarta-commons/cli/src/test/org/apache/commons/cli2 DocumentationTest.java
Date Mon, 27 Dec 2004 17:41:28 GMT
roxspring    2004/12/27 09:41:28

  Modified:    cli/xdocs/examples ant.xml
               cli/src/test/org/apache/commons/cli2 DocumentationTest.java
  Log:
  Documented ant example
  
  Revision  Changes    Path
  1.2       +266 -1    jakarta-commons/cli/xdocs/examples/ant.xml
  
  Index: ant.xml
  ===================================================================
  RCS file: /home/cvs/jakarta-commons/cli/xdocs/examples/ant.xml,v
  retrieving revision 1.1
  retrieving revision 1.2
  diff -u -r1.1 -r1.2
  --- ant.xml	2 Sep 2004 13:58:16 -0000	1.1
  +++ ant.xml	27 Dec 2004 17:41:27 -0000	1.2
  @@ -23,12 +23,277 @@
   
     <body>
       <section name="ant">
  -      <p>TODO what is ant</p>
  +      <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 used 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>
  
  
  
  1.3       +57 -4     jakarta-commons/cli/src/test/org/apache/commons/cli2/DocumentationTest.java
  
  Index: DocumentationTest.java
  ===================================================================
  RCS file: /home/cvs/jakarta-commons/cli/src/test/org/apache/commons/cli2/DocumentationTest.java,v
  retrieving revision 1.2
  retrieving revision 1.3
  diff -u -r1.2 -r1.3
  --- DocumentationTest.java	22 Apr 2004 23:00:06 -0000	1.2
  +++ DocumentationTest.java	27 Dec 2004 17:41:27 -0000	1.3
  @@ -18,6 +18,8 @@
   import java.io.IOException;
   import java.io.PrintWriter;
   import java.io.StringWriter;
  +import java.util.Iterator;
  +import java.util.List;
   
   import junit.framework.TestCase;
   
  @@ -147,8 +149,8 @@
           }
       }
   
  -    public void testExampleAnt() throws IOException {
  -        // Based on Ant 1.5.3
  +    public void testExampleAnt() throws IOException, OptionException {
  +        // Apache Ant version 1.6.1 compiled on February 12 2004
   
           final DefaultOptionBuilder obuilder = new DefaultOptionBuilder();
           final ArgumentBuilder abuilder = new ArgumentBuilder();
  @@ -157,11 +159,13 @@
           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 =
  @@ -189,18 +193,31 @@
           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("produce logging information without adornments")
  +                .withDescription("use given file for log")
                   .withArgument(
                       abuilder
                           .withName("file")
  @@ -230,11 +247,16 @@
                           .withMaximum(1)
                           .create())
                   .create();
  +        Option noinput =
  +            obuilder
  +                .withShortName("noinput")
  +                .withDescription("do not allow interactive input")
  +                .create();
           Option buildfile =
               obuilder
                   .withShortName("buildfile")
  -                .withShortName("b")
                   .withShortName("file")
  +                .withShortName("f")
                   .withDescription("use given buildfile")
                   .withArgument(
                       abuilder
  @@ -269,6 +291,7 @@
           Option find =
               obuilder
                   .withShortName("find")
  +                .withShortName("s")
                   .withDescription("search for buildfile towards the root of the filesystem
and use it")
                   .withArgument(
                       abuilder
  @@ -290,9 +313,11 @@
                   .withOption(verbose)
                   .withOption(debug)
                   .withOption(emacs)
  +                .withOption(lib)
                   .withOption(logfile)
                   .withOption(logger)
                   .withOption(listener)
  +                .withOption(noinput)
                   .withOption(buildfile)
                   .withOption(property)
                   .withOption(propertyfile)
  @@ -300,6 +325,33 @@
                   .withOption(find)
                   .withOption(targets)
                   .create();
  +        
  +        /////////////////////////////////////
  +        String[] args = new String[]{};
  +        
  +        Parser parser = new Parser();
  +        parser.setGroup(options);
  +        CommandLine cl = parser.parse(args);
  +        
  +        if(cl.hasOption(help)) {
  +            //displayHelp();
  +            return;
  +        }
  +        if(cl.hasOption("-version")) {
  +            //displayVersion();
  +            return;
  +        }
  +        if(cl.hasOption(logfile)) {
  +            String file = (String)cl.getValue(logfile);
  +            //setLogFile();
  +        }
  +        List targetList = cl.getValues(targets);
  +        for (Iterator i = targetList.iterator(); i.hasNext();) {
  +            String target = (String) i.next();
  +            //doTarget(target);
  +        }
  +        
  +        /////////////////////////////////////
   
           HelpFormatter hf = new HelpFormatter();
           hf.setShellCommand("ant");
  @@ -309,6 +361,7 @@
   
           hf.getLineUsageSettings().add(DisplaySetting.DISPLAY_PROPERTY_OPTION);
           hf.getLineUsageSettings().add(DisplaySetting.DISPLAY_PARENT_ARGUMENT);
  +        hf.getLineUsageSettings().add(DisplaySetting.DISPLAY_ARGUMENT_BRACKETED);
   
           hf.getDisplaySettings().remove(DisplaySetting.DISPLAY_GROUP_ARGUMENT);
   
  
  
  

---------------------------------------------------------------------
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