Displaying correct usage for commands

6 files changed, 107 insertions, 37 deletions

diff --git a/src/main/java/com/beust/jcommander/JCommander.java b/src/main/java/com/beust/jcommander/JCommander.java
index a0aeda3..76ed929 100644
--- a/src/main/java/com/beust/jcommander/JCommander.java
+++ b/src/main/java/com/beust/jcommander/JCommander.java
@@ -97,6 +97,8 @@ public class JCommander {
    */
   private String m_parsedCommand;
 
+  private String m_programName;
+
   /**
    * The factories used to look up string converters.
    */
@@ -540,20 +542,68 @@ public class JCommander {
     }
   }
 
+  private String getMainParameterDescription() {
+    if (m_descriptions == null) createDescriptions();
+    return m_mainParameterAnnotation != null ? m_mainParameterAnnotation.description()
+        : null;
+  }
+
+  private int longestName(Collection<?> objects) {
+    int result = 0;
+    for (Object o : objects) {
+      int l = o.toString().length();
+      if (l > result) result = l;
+    }
+
+    return result;
+  }
+
+  public void usage(String commandName) {
+    Object o = m_commands.get(commandName);
+    Object object;
+    try {
+      // Create a new object since o might have received values
+      // and might therefore display default values that are incorrect.
+      object = o.getClass().newInstance();
+      JCommander jc = new JCommander(object);
+      jc.setProgramName(commandName);
+      jc.usage();
+    } catch (InstantiationException e) {
+      e.printStackTrace();
+    } catch (IllegalAccessException e) {
+      e.printStackTrace();
+    }
+  }
+
+  /**
+   * Set the program name (used only in the usage).
+   */
+  public void setProgramName(String name) {
+    m_programName = name;
+  }
+
   /**
    * Display a the help on System.out.
    */
   public void usage() {
     if (m_descriptions == null) createDescriptions();
+    boolean hasCommands = ! m_commands.isEmpty();
 
-    StringBuilder sb = new StringBuilder("Usage: <main class> [options]");
+    //
+    // First line of the usage
+    //
+    String programName = m_programName != null ? m_programName : "<main class>";
+    StringBuilder sb = new StringBuilder("Usage: " + programName + " [options]");
+    if (hasCommands) sb.append(" [command] [command options]");
     if (m_mainParameterAnnotation != null) {
       sb.append(" " + m_mainParameterAnnotation.description());
     }
     sb.append("\n  Options:");
     System.out.println(sb.toString());
 
-    // Will contain the size of the longest option name
+    // 
+    // Align the descriptions at the "longestName" column
+    //
     int longestName = 0;
     List<ParameterDescription> sorted = Lists.newArrayList();
     for (ParameterDescription pd : m_fields.values()) {
@@ -567,6 +617,9 @@ public class JCommander {
       }
     }
 
+    //
+    // Sort the options
+    //
     Collections.sort(sorted, new Comparator<ParameterDescription>() {
       @Override
       public int compare(ParameterDescription arg0, ParameterDescription arg1) {
@@ -574,19 +627,21 @@ public class JCommander {
       }
     });
 
-    // Display all the names and descriptions at the right tab position
+    //
+    // Display all the names and descriptions
+    //
     StringBuilder out = new StringBuilder();
     for (ParameterDescription pd : sorted) {
       int l = pd.getNames().length();
       int spaceCount = longestName - l;
-      StringBuilder tabs = new StringBuilder();
-      for (int i = 0; i < spaceCount; i++) tabs.append(" ");
       out.append("  "
           + (pd.getParameter().required() ? "* " : "  ")
-          + pd.getNames() + tabs + pd.getDescription());
+          + pd.getNames() + s(spaceCount) + pd.getDescription());
       try {
-        Object def = pd.getField().get(pd.getObject());
-        if (def != null) out.append(" (default: " + def + ")");
+        if (! pd.wasAssigned()) {
+          Object def = pd.getField().get(pd.getObject());
+          if (def != null) out.append(" (default: " + def + ")");
+        }
       } catch (IllegalArgumentException e) {
         // ignore
       } catch (IllegalAccessException e) {
@@ -595,6 +650,21 @@ public class JCommander {
       out.append("\n");
     }
 
+    //
+    // If commands were specified, show them as well
+    //
+    if (hasCommands) {
+      out.append("  Commands:\n");
+      int ln = longestName(m_commands.keySet()) + 3;
+      for (Map.Entry<String, Object> commands : m_commands.entrySet()) {
+        String name = commands.getKey();
+        int spaceCount  = ln - name.length();
+        Object o = commands.getValue();
+        JCommander jc = new JCommander(o);
+        out.append("    " + name + s(spaceCount) + jc.getMainParameterDescription() + "\n");
+      }
+    }
+
     System.out.println(out);
   }
 
@@ -729,5 +799,16 @@ public class JCommander {
     return m_parsedCommand;
   }
 
+  /**
+   * @return n spaces
+   */
+  private String s(int count) {
+    StringBuilder result = new StringBuilder();
+    for (int i = 0; i < count; i++) {
+      result.append(" ");
+    }
+
+    return result.toString();
+  }
 }
 
diff --git a/src/main/java/com/beust/jcommander/ParameterDescription.java b/src/main/java/com/beust/jcommander/ParameterDescription.java
index ffe9c95..fdac1d8 100644
--- a/src/main/java/com/beust/jcommander/ParameterDescription.java
+++ b/src/main/java/com/beust/jcommander/ParameterDescription.java
@@ -1,13 +1,9 @@
 package com.beust.jcommander;
 
 
-import com.beust.jcommander.converters.NoConverter;
-import com.beust.jcommander.converters.StringConverter;
 import com.beust.jcommander.internal.Lists;
 
-import java.lang.reflect.Constructor;
 import java.lang.reflect.Field;
-import java.lang.reflect.InvocationTargetException;
 import java.util.Collection;
 import java.util.List;
 import java.util.Locale;
@@ -112,6 +108,13 @@ public class ParameterDescription {
   }
 
   /**
+   * @return true if this parameter received a value during the parsing phase.
+   */
+  public boolean wasAssigned() {
+    return m_assigned;
+  }
+
+  /**
    * Add the specified value to the field. First look up any field converter, then
    * any type converter, and if we can't find any, throw an exception.
    * 
@@ -126,28 +129,6 @@ public class ParameterDescription {
     }
 
     Class<?> type = m_field.getType();
-//    Class<? extends IStringConverter<?>> converterClass = null;
-//
-//    //
-//    // Try to find a converter on the annotation
-//    //
-//    converterClass = m_parameterAnnotation.converter();
-//    if (converterClass == NoConverter.class) {
-//      converterClass = m_jCommander.findConverter(type);
-//    }
-//    if (converterClass == null && m_parameterAnnotation.arity() >= 2) {
-//      converterClass = StringConverter.class;
-//      isCollection = true;
-//    }
-//    if (converterClass == null && Collection.class.isAssignableFrom(type)) {
-//      converterClass = StringConverter.class;
-//      isCollection = true;
-//    }
-//
-//    if (converterClass == null) {
-//      throw new ParameterException("Don't know how to convert " + value
-//          + " to type " + type + " (field: " + m_field.getName() + ")");
-//    }
 
     if (! isDefault) m_assigned = true;
     Object convertedValue = m_jCommander.convertValue(this, value);
@@ -189,4 +170,9 @@ public class ParameterDescription {
       System.out.println("[ParameterDescription] " + string);
     }
   }
+
+  @Override
+  public String toString() {
+    return "[ParameterDescription " + m_field.getName() + "]";
+  }
 }
diff --git a/src/test/java/com/beust/jcommander/JCommanderTest.java b/src/test/java/com/beust/jcommander/JCommanderTest.java
index c413e34..9146fd3 100644
--- a/src/test/java/com/beust/jcommander/JCommanderTest.java
+++ b/src/test/java/com/beust/jcommander/JCommanderTest.java
@@ -294,7 +294,7 @@ public class JCommanderTest {
 
   public static void main(String[] args) {
 //    new JCommanderTest().commandTest2();
-//    new ConverterFactoryTest().mainWithHostPortParameters();
+//    new CommandTest().commandTest2();
 //    new DefaultProviderTest().defaultProvider1();
 //    ArgsMainParameter a = new ArgsMainParameter();
 //    new JCommander(a, "ex1:10", "ex2:20");
diff --git a/src/test/java/com/beust/jcommander/command/CommandAdd.java b/src/test/java/com/beust/jcommander/command/CommandAdd.java
index 227a8f2..230b92b 100644
--- a/src/test/java/com/beust/jcommander/command/CommandAdd.java
+++ b/src/test/java/com/beust/jcommander/command/CommandAdd.java
@@ -6,7 +6,7 @@ import java.util.List;
 
 public class CommandAdd {
 
-  @Parameter
+  @Parameter(description = "Add file contents to the index")
   public List<String> patterns;
 
   @Parameter(names = "-i")
diff --git a/src/test/java/com/beust/jcommander/command/CommandCommit.java b/src/test/java/com/beust/jcommander/command/CommandCommit.java
index c328756..1c22b72 100644
--- a/src/test/java/com/beust/jcommander/command/CommandCommit.java
+++ b/src/test/java/com/beust/jcommander/command/CommandCommit.java
@@ -8,7 +8,7 @@ import java.util.List;
 @Parameters(separators = "=")
 public class CommandCommit {
 
-  @Parameter
+  @Parameter(description = "Record changes to the repository")
   public List<String> files;
 
   @Parameter(names = "--amend", description = "Amend")
diff --git a/src/test/java/com/beust/jcommander/command/CommandTest.java b/src/test/java/com/beust/jcommander/command/CommandTest.java
index ebdf1da..f01a082 100644
--- a/src/test/java/com/beust/jcommander/command/CommandTest.java
+++ b/src/test/java/com/beust/jcommander/command/CommandTest.java
@@ -32,6 +32,9 @@ public class CommandTest {
     CommandCommit commit = new CommandCommit();
     jc.addCommand("commit", commit);
     jc.parse("-v", "commit", "--amend", "--author=cbeust", "A.java", "B.java");
+//    jc.usage();
+//    jc.usage("add");
+//    jc.usage("commit");
 
     Assert.assertTrue(cm.verbose);
     Assert.assertEquals(jc.getParsedCommand(), "commit");