added automatic usage generation

John Keyes · John Keyes · commit c7127329dad2 · 2002-07-22T22:49:58.000Z
git-svn-id: https://svn.apache.org/repos/asf/jakarta/commons/proper/cli/trunk@129785 13f79535-47bb-0310-9956-ffa450edef68
diff --git a/src/java/org/apache/commons/cli/HelpFormatter.java b/src/java/org/apache/commons/cli/HelpFormatter.java
@@ -62,11 +62,12 @@
 package org.apache.commons.cli;
 
 import java.io.PrintWriter;
-import java.util.Iterator;
-import java.util.List;
 import java.util.ArrayList;
+import java.util.Collection;
 import java.util.Collections;
 import java.util.Comparator;
+import java.util.Iterator;
+import java.util.List;
 
 /** 
  * A formatter of help messages for the current command line options
@@ -117,29 +118,54 @@ public HelpFormatter()
    public void printHelp( String cmdLineSyntax,
                           Options options )
    {
-      printHelp( defaultWidth, cmdLineSyntax, null, options, null );
+       printHelp( defaultWidth, cmdLineSyntax, null, options, null, false );
+   }
+
+   public void printHelp( String cmdLineSyntax,
+                          Options options,
+                          boolean autoUsage )
+   {
+       printHelp( defaultWidth, cmdLineSyntax, null, options, null, autoUsage );
    }
 
    public void printHelp( String cmdLineSyntax,
                           String header,
                           Options options,
                           String footer )
    {
-      printHelp(defaultWidth, cmdLineSyntax, header, options, footer);
+       printHelp( cmdLineSyntax, header, options, footer, false );
    }
 
+   public void printHelp( String cmdLineSyntax,
+                          String header,
+                          Options options,
+                          String footer,
+                          boolean autoUsage )
+   {
+      printHelp(defaultWidth, cmdLineSyntax, header, options, footer, autoUsage );
+   }
+   
    public void printHelp( int width,
                           String cmdLineSyntax,
                           String header,
                           Options options,
                           String footer )
+   {
+       printHelp( width, cmdLineSyntax, header, options, footer, false );
+   }
+
+   public void printHelp( int width,
+                          String cmdLineSyntax,
+                          String header,
+                          Options options,
+                          String footer,
+                          boolean autoUsage )
    {
       PrintWriter pw = new PrintWriter(System.out);
       printHelp( pw, width, cmdLineSyntax, header,
-                 options, defaultLeftPad, defaultDescPad, footer );
+                 options, defaultLeftPad, defaultDescPad, footer, autoUsage );
       pw.flush();
    }
-
    public void printHelp( PrintWriter pw,
                           int width,
                           String cmdLineSyntax,
@@ -148,14 +174,34 @@ public void printHelp( PrintWriter pw,
                           int leftPad,
                           int descPad,
                           String footer )
+   throws IllegalArgumentException
+   {
+       printHelp( pw, width, cmdLineSyntax, header, options, leftPad, descPad, footer, false );
+   }
+
+   public void printHelp( PrintWriter pw,
+                          int width,
+                          String cmdLineSyntax,
+                          String header,
+                          Options options,
+                          int leftPad,
+                          int descPad,
+                          String footer,
+                          boolean autoUsage )
       throws IllegalArgumentException
    {
       if ( cmdLineSyntax == null || cmdLineSyntax.length() == 0 )
       {
          throw new IllegalArgumentException("cmdLineSyntax not provided");
       }
 
-      printUsage( pw, width, cmdLineSyntax );
+      if ( autoUsage ) {
+          printUsage( pw, width, cmdLineSyntax, options );
+      }
+      else {
+          printUsage( pw, width, cmdLineSyntax );
+      }
+
       if ( header != null && header.trim().length() > 0 )
       {
          printWrapped( pw, width, header );
@@ -167,6 +213,83 @@ public void printHelp( PrintWriter pw,
       }
    }
 
+   /**
+    * <p>Prints the usage statement for the specified application.</p>
+    *
+    * @param pw The PrintWriter to print the usage statement 
+    * @param width ??
+    * @param appName The application name
+    * @param options The command line Options
+    *
+    */
+   public void printUsage( PrintWriter pw, int width, String app, Options options ) 
+   {
+       // initialise the string buffer
+       StringBuffer buff = new StringBuffer( defaultSyntaxPrefix ).append( app ).append( " " );
+       
+       // create a list for processed option groups
+       ArrayList list = new ArrayList();
+
+       // temp variable
+       Option option;
+
+       // iterate over the options
+       for ( Iterator i = options.getOptions().iterator(); i.hasNext(); )
+       {
+           // get the next Option
+           option = (Option) i.next();
+
+           // check if the option is part of an OptionGroup
+           OptionGroup group = options.getOptionGroup( option );
+
+           // if the option is part of a group and the group has not already
+           // been processed
+           if( group != null && !list.contains(group)) {
+
+               // add the group to the processed list
+               list.add( group );
+
+               // get the names of the options from the OptionGroup
+               Collection names = group.getNames();
+
+               buff.append( "[" ); 
+
+               // for each option in the OptionGroup
+               for( Iterator iter = names.iterator(); iter.hasNext(); ) {
+                   buff.append( iter.next() );
+                   if( iter.hasNext() ) {
+                       buff.append( " | " );
+                   }
+               }
+               buff.append( "]" );
+           }
+           // if the Option is not part of an OptionGroup
+           else {
+               // if the Option is not a required option
+               if( !option.isRequired() ) {
+                   buff.append( "[" );
+               }
+               buff.append( "-" ).append( option.getOpt() );
+
+               // if the Option has a value
+               if( option.hasArg() ) {
+                   buff.append( " arg" );
+               }
+
+               // if the Option is not a required option
+               if( !option.isRequired() ) {
+                   buff.append( "]" );
+               }
+               buff.append( " " );
+           }
+       }
+
+       System.out.println( "->" + buff.toString() );
+       // call printWrapped
+       printWrapped( pw, width, buff.toString().indexOf(' ')+1,
+                     buff.toString() );
+   }
+
    public void printUsage( PrintWriter pw, int width, String cmdLineSyntax )
    {
       int argPos = cmdLineSyntax.indexOf(' ') + 1;
diff --git a/src/java/org/apache/commons/cli/OptionGroup.java b/src/java/org/apache/commons/cli/OptionGroup.java
@@ -94,7 +94,7 @@ public OptionGroup addOption(Option opt) {
      * @return the names of the options in this group as a 
      * <code>Collection</code>
      */
-    private Collection getNames() {
+    public Collection getNames() {
         // the key set is the collection of names
         return optionMap.keySet();
     }
diff --git a/src/test/org/apache/commons/cli/TestHelpFormatter.java b/src/test/org/apache/commons/cli/TestHelpFormatter.java
@@ -12,21 +12,18 @@
 import junit.framework.TestCase;
 import junit.framework.TestSuite;
 
-import java.io.StringWriter;
+import java.io.ByteArrayOutputStream;
 import java.io.PrintWriter;
+import java.io.StringWriter;
 
 /** 
  * Test case for the HelpFormatter class 
  *
  * @author Slawek Zachcial
+ * @author John Keyes ( jbjk at mac.com )
  **/
-public class TestHelpFormatter
-extends TestCase
+public class TestHelpFormatter extends TestCase
 {
-   // --------------------------------------------------------------- Constants
-
-   // ------------------------------------------------------------------ Static
-
    public static void main( String[] args )
    {
       String[] testName = { TestHelpFormatter.class.getName() };
@@ -38,14 +35,10 @@ public static TestSuite suite()
       return new TestSuite(TestHelpFormatter.class);
    }
 
-   // -------------------------------------------------------------- Attributes
-
-   // ------------------------------------------------------------ Constructors
    public TestHelpFormatter( String s )
    {
       super( s );
    }
-   // ------------------------------------------------------------------ Public
 
    public void testFindWrapPos()
       throws Exception
@@ -100,64 +93,79 @@ public void testPrintWrapped()
    }
 
    public void testPrintOptions()
-      throws Exception
+   throws Exception
    {
-      StringBuffer sb = new StringBuffer();
-      HelpFormatter hf = new HelpFormatter();
-      final int leftPad = 1;
-      final int descPad = 3;
-      final String lpad = hf.createPadding(leftPad);
-      final String dpad = hf.createPadding(descPad);
-      Options options = null;
-      String expected = null;
-
-      options = new Options().addOption("a", false, "aaaa aaaa aaaa aaaa aaaa");
-      expected = lpad + "-a" + dpad + "aaaa aaaa aaaa aaaa aaaa";
-      hf.renderOptions(sb, 60, options, leftPad, descPad);
-      assertEquals("simple non-wrapped option", expected, sb.toString());
-
-      int nextLineTabStop = leftPad+descPad+"-a".length();
-      expected =
-         lpad + "-a" + dpad + "aaaa aaaa aaaa" + hf.defaultNewLine +
-         hf.createPadding(nextLineTabStop) + "aaaa aaaa";
-      sb.setLength(0);
-      hf.renderOptions(sb, nextLineTabStop+17, options, leftPad, descPad);
-      assertEquals("simple wrapped option", expected, sb.toString());
-
-
-      options = new Options().addOption("a", "aaa", false, "dddd dddd dddd dddd");
-      expected = lpad + "-a,--aaa" + dpad + "dddd dddd dddd dddd";
-      sb.setLength(0);
-      hf.renderOptions(sb, 60, options, leftPad, descPad);
-      assertEquals("long non-wrapped option", expected, sb.toString());
-
-      nextLineTabStop = leftPad+descPad+"-a,--aaa".length();
-      expected =
-         lpad + "-a,--aaa" + dpad + "dddd dddd" + hf.defaultNewLine +
-         hf.createPadding(nextLineTabStop) + "dddd dddd";
-      sb.setLength(0);
-      hf.renderOptions(sb, 25, options, leftPad, descPad);
-      assertEquals("long wrapped option", expected, sb.toString());
-
-      options = new Options().
-         addOption("a", "aaa", false, "dddd dddd dddd dddd").
-         addOption("b", false, "feeee eeee eeee eeee");
-      expected =
-         lpad + "-a,--aaa" + dpad + "dddd dddd" + hf.defaultNewLine +
-         hf.createPadding(nextLineTabStop) + "dddd dddd" + hf.defaultNewLine +
-         lpad + "-b      " + dpad + "feeee eeee" + hf.defaultNewLine +
-         hf.createPadding(nextLineTabStop) + "eeee eeee";
-      sb.setLength(0);
-      hf.renderOptions(sb, 25, options, leftPad, descPad);
-      assertEquals("multiple wrapped options", expected, sb.toString());
+       StringBuffer sb = new StringBuffer();
+       HelpFormatter hf = new HelpFormatter();
+       final int leftPad = 1;
+       final int descPad = 3;
+       final String lpad = hf.createPadding(leftPad);
+       final String dpad = hf.createPadding(descPad);
+       Options options = null;
+       String expected = null;
+
+       options = new Options().addOption("a", false, "aaaa aaaa aaaa aaaa aaaa");
+       expected = lpad + "-a" + dpad + "aaaa aaaa aaaa aaaa aaaa";
+       hf.renderOptions(sb, 60, options, leftPad, descPad);
+       assertEquals("simple non-wrapped option", expected, sb.toString());
+
+       int nextLineTabStop = leftPad+descPad+"-a".length();
+       expected =
+           lpad + "-a" + dpad + "aaaa aaaa aaaa" + hf.defaultNewLine +
+           hf.createPadding(nextLineTabStop) + "aaaa aaaa";
+       sb.setLength(0);
+       hf.renderOptions(sb, nextLineTabStop+17, options, leftPad, descPad);
+       assertEquals("simple wrapped option", expected, sb.toString());
+
+
+       options = new Options().addOption("a", "aaa", false, "dddd dddd dddd dddd");
+       expected = lpad + "-a,--aaa" + dpad + "dddd dddd dddd dddd";
+       sb.setLength(0);
+       hf.renderOptions(sb, 60, options, leftPad, descPad);
+       assertEquals("long non-wrapped option", expected, sb.toString());
+
+       nextLineTabStop = leftPad+descPad+"-a,--aaa".length();
+       expected =
+           lpad + "-a,--aaa" + dpad + "dddd dddd" + hf.defaultNewLine +
+           hf.createPadding(nextLineTabStop) + "dddd dddd";
+       sb.setLength(0);
+       hf.renderOptions(sb, 25, options, leftPad, descPad);
+       assertEquals("long wrapped option", expected, sb.toString());
+
+       options = new Options().
+           addOption("a", "aaa", false, "dddd dddd dddd dddd").
+           addOption("b", false, "feeee eeee eeee eeee");
+       expected =
+           lpad + "-a,--aaa" + dpad + "dddd dddd" + hf.defaultNewLine +
+           hf.createPadding(nextLineTabStop) + "dddd dddd" + hf.defaultNewLine +
+           lpad + "-b      " + dpad + "feeee eeee" + hf.defaultNewLine +
+           hf.createPadding(nextLineTabStop) + "eeee eeee";
+       sb.setLength(0);
+       hf.renderOptions(sb, 25, options, leftPad, descPad);
+       assertEquals("multiple wrapped options", expected, sb.toString());
    }
 
-   // --------------------------------------------------------------- Protected
-
-   // ------------------------------------------------------- Package protected   
-   
-   // ----------------------------------------------------------------- Private
-   
-   // ----------------------------------------------------------- Inner classes
-
+   public void testAutomaticUsage()
+   throws Exception
+   {
+       HelpFormatter hf = new HelpFormatter();
+       Options options = null;
+       String expected = "usage: app [-a]\n";
+       ByteArrayOutputStream out = new ByteArrayOutputStream( );
+       PrintWriter pw = new PrintWriter( out );
+
+       options = new Options().addOption("a", false, "aaaa aaaa aaaa aaaa aaaa");
+       hf.printUsage( pw, 60, "app", options );
+       pw.flush();
+       assertEquals("simple auto usage", expected, out.toString());
+       out.reset();
+
+       expected = "usage: app [-b] [-a]\n";
+       options = new Options().addOption("a", false, "aaaa aaaa aaaa aaaa aaaa")
+       .addOption("b", false, "bbb" );
+       hf.printUsage( pw, 60, "app", options );
+       pw.flush();
+       assertEquals("simple auto usage", expected, out.toString());
+       out.reset();
+   }
 }

Original file line number	Diff line number	Diff line change
`@@ -94,7 +94,7 @@ public OptionGroup addOption(Option opt) {`
`94`	`94`	`* @return the names of the options in this group as a`
`95`	`95`	`* <code>Collection</code>`
`96`	`96`	`*/`
`97`		`- private Collection getNames() {`
	`97`	`+ public Collection getNames() {`
`98`	`98`	`// the key set is the collection of names`
`99`	`99`	`return optionMap.keySet();`
`100`	`100`	`}`