Added @Hidden annotation, a way to deliberately exclude experimental fields and

walkers from the help system.


git-svn-id: file:///humgen/gsa-scr1/gsa-engineering/svn_contents/trunk@3946 348d0f76-0448-11de-a6fe-93d51630548a

java/src/org/broadinstitute/sting/commandline/ArgumentDefinition.java

@@ -70,6 +70,11 @@ public class ArgumentDefinition {
      */
     public final boolean isMultiValued;
 
+    /**
+     * Is this argument hidden from the help system?
+     */
+    public final boolean isHidden;
+    
     /**
      * Is this argument exclusive of other arguments?
      */
@@ -94,6 +99,7 @@ public class ArgumentDefinition {
      * @param required Whether or not this argument is required.
      * @param isFlag Whether or not this argument should be treated as a flag.
      * @param isMultiValued Whether or not this argument supports multiple values.
+     * @param isHidden Whether or not this argument should be hidden from the command-line argument system.
      * @param exclusiveOf Whether this command line argument is mutually exclusive of other arguments.
      * @param validation A regular expression for command-line argument validation.
      * @param validOptions is there a particular list of options that's valid for this argument definition?  List them if so, otherwise set this to null. 
@@ -105,6 +111,7 @@ public class ArgumentDefinition {
                                boolean required,
                                boolean isFlag,
                                boolean isMultiValued,
+                               boolean isHidden,
                                String exclusiveOf,
                                String validation,
                                List<String> validOptions) {
@@ -115,6 +122,7 @@ public class ArgumentDefinition {
         this.required = required;
         this.isFlag = isFlag;
         this.isMultiValued = isMultiValued;
+        this.isHidden = isHidden;
         this.exclusiveOf = exclusiveOf;
         this.validation = validation;
         this.validOptions = validOptions;
@@ -127,6 +135,7 @@ public class ArgumentDefinition {
      * @param defaultShortName Default short name for this argument definition.
      * @param isFlag Whether or not this argument should be treated as a flag.
      * @param isMultiValued Whether or not this argument supports multiple values.
+     * @param isHidden Whether or not this argument should be hidden from the command-line argument system.
      * @param validOptions is there a particular list of options that's valid for this argument definition?  List them if so, otherwise set this to null.
      */
     public ArgumentDefinition( Annotation annotation,
@@ -134,6 +143,7 @@ public class ArgumentDefinition {
                                String defaultShortName,
                                boolean isFlag,
                                boolean isMultiValued,
+                               boolean isHidden,
                                List<String> validOptions) {
 
         String fullName = (String)getValue(annotation, "fullName");
@@ -159,6 +169,7 @@ public class ArgumentDefinition {
         this.required = isRequired(annotation, isFlag);
         this.isFlag = isFlag;
         this.isMultiValued = isMultiValued;
+        this.isHidden = isHidden;
         this.exclusiveOf = getExclusiveOf(annotation);
         this.validation = getValidationRegex(annotation);
         this.validOptions = validOptions;
@@ -170,12 +181,14 @@ public class ArgumentDefinition {
      * @param fieldName Default full name for this argument definition.
      * @param isFlag Whether or not this argument should be treated as a flag.
      * @param isMultiValued Whether or not this argument supports multiple values.
+     * @param isHidden Whether or not this argument should be hidden from the command-line argument system.
      * @param validOptions is there a particular list of options that's valid for this argument definition?  List them if so, otherwise set this to null.
      */
     public ArgumentDefinition( Annotation annotation,
                                String fieldName,
                                boolean isFlag,
                                boolean isMultiValued,
+                               boolean isHidden,
                                List<String> validOptions) {
         this.ioType = getIOType(annotation);
         this.fullName = getFullName(annotation, fieldName);
@@ -184,6 +197,7 @@ public class ArgumentDefinition {
         this.required = isRequired(annotation, isFlag);
         this.isFlag = isFlag;
         this.isMultiValued = isMultiValued;
+        this.isHidden = isHidden;
         this.exclusiveOf = getExclusiveOf(annotation);
         this.validation = getValidationRegex(annotation);
         this.validOptions = validOptions;

java/src/org/broadinstitute/sting/commandline/ArgumentDefinitionGroup.java

@@ -86,4 +86,16 @@ public class ArgumentDefinitionGroup implements Iterable<ArgumentDefinition> {
     public Iterator<ArgumentDefinition> iterator() {
         return argumentDefinitions.iterator();
     }
+
+    /**
+     * Reports whether all the arguments in this group are hidden.
+     * @return True if all are hidden, false if some or none are hidden.
+     */
+    public boolean allHidden() {
+        for(ArgumentDefinition argumentDefinition: argumentDefinitions) {
+            if(!argumentDefinition.isHidden)
+                return false;
+        }
+        return true;
+    }
 }

java/src/org/broadinstitute/sting/commandline/ArgumentSource.java

@@ -25,6 +25,8 @@
 
 package org.broadinstitute.sting.commandline;
 
+import org.broadinstitute.sting.gatk.walkers.Hidden;
+
 import java.lang.reflect.Field;
 import java.util.Collection;
 import java.util.List;
@@ -147,6 +149,14 @@ public class ArgumentSource {
         return Collection.class.isAssignableFrom(argumentType) || field.getType().isArray();
     }
 
+    /**
+     * Should the given class be hidden from the command-line argument system.
+     * @return True if so.  False otherwise.
+     */
+    public boolean isHidden() {
+        return field.isAnnotationPresent(Hidden.class);
+    }
+
     /**
      * Gets a string representation of the argument source for debugging.
      * @return String representation of the argument source.

java/src/org/broadinstitute/sting/commandline/ArgumentTypeDescriptor.java

@@ -26,6 +26,7 @@
 package org.broadinstitute.sting.commandline;
 
 import org.broadinstitute.sting.utils.StingException;
+import org.broadinstitute.sting.gatk.walkers.Hidden;
 import org.apache.log4j.Logger;
 
 import java.lang.annotation.Annotation;
@@ -127,6 +128,7 @@ public abstract class ArgumentTypeDescriptor {
                                        source.field.getName(),
                                        source.isFlag(),
                                        source.isMultiValued(),
+                                       source.isHidden(),
                                        getValidOptions(source) );
     }
 
@@ -198,6 +200,15 @@ public abstract class ArgumentTypeDescriptor {
                 return true;
         return false;
     }
+
+    /**
+     * Returns true if the given annotation is hidden from the help system.
+     * @param field Field to test.
+     * @return True if argument should be hidden.  False otherwise.
+     */
+    public static boolean isArgumentHidden(Field field) {
+        return field.isAnnotationPresent(Hidden.class);
+    }
 }
 
 /**

java/src/org/broadinstitute/sting/gatk/CommandLineGATK.java

@@ -187,7 +187,7 @@ public class CommandLineGATK extends CommandLineExecutable {
         
         int longestPackageName = 0;
         int longestWalkerName = 0;
-        for(Map.Entry<String,Collection<Class<? extends Walker>>> walkersByPackage: walkerManager.getWalkerNamesByPackage().entrySet()) {
+        for(Map.Entry<String,Collection<Class<? extends Walker>>> walkersByPackage: walkerManager.getWalkerNamesByPackage(true).entrySet()) {
             // Get the display name.
             String packageName = walkersByPackage.getKey();
             String packageDisplayName = walkerManager.getPackageDisplayName(walkersByPackage.getKey());

java/src/org/broadinstitute/sting/gatk/WalkerManager.java

@@ -66,11 +66,15 @@ public class WalkerManager extends PluginManager<Walker> {
     /**
      * Get the list of walkers currently available to the GATK, organized
      * by package.
+     * @param visibleWalkersOnly If true, return only the walker names that aren't hidden.
      * @return Names of currently available walkers.
      */
-    public Map<String,Collection<Class<? extends Walker>>> getWalkerNamesByPackage() {
+    public Map<String,Collection<Class<? extends Walker>>> getWalkerNamesByPackage(boolean visibleWalkersOnly) {
         Map<String,Collection<Class<? extends Walker>>> walkersByPackage = new HashMap<String,Collection<Class<? extends Walker>>>();
         for(Class<? extends Walker> walker: pluginsByName.values()) {
+            if(visibleWalkersOnly && isHidden(walker))
+                continue;
+
             // Extract the name for the package; if the walker is in the unnamed package, use the empty string
             String walkerPackage = walker.getPackage() != null ? walker.getPackage().getName() : "";
             if(!walkersByPackage.containsKey(walkerPackage))
@@ -225,6 +229,15 @@ public class WalkerManager extends PluginManager<Walker> {
         return Arrays.asList(requiresDataSource.referenceMetaData());
     }
 
+    /**
+     * Reports whether this walker type is hidden -- in other words, whether it'll appear in the help output.
+     * @param walkerType Class to test for visibility.
+     * @return True if the walker should be hidden.  False otherwise.
+     */
+    public static boolean isHidden(Class<? extends Walker> walkerType) {
+        return walkerType.isAnnotationPresent(Hidden.class);    
+    }
+
     /**
      * Extracts filters that the walker has requested be run on the dataset.
      * @param walker Walker to inspect for filtering requests.

java/src/org/broadinstitute/sting/gatk/io/stubs/GenotypeWriterArgumentTypeDescriptor.java

@@ -162,6 +162,7 @@ public class GenotypeWriterArgumentTypeDescriptor extends ArgumentTypeDescriptor
                                        "varout",
                                        false,
                                        source.isMultiValued(),
+                                       source.isHidden(),
                                        null );
     }
 
@@ -179,6 +180,7 @@ public class GenotypeWriterArgumentTypeDescriptor extends ArgumentTypeDescriptor
                                        false,
                                        false,
                                        false,
+                                       source.isHidden(),
                                        null,
                                        null,
                                        null );

java/src/org/broadinstitute/sting/gatk/io/stubs/SAMFileWriterArgumentTypeDescriptor.java

@@ -101,6 +101,7 @@ public class SAMFileWriterArgumentTypeDescriptor extends ArgumentTypeDescriptor
                                        DEFAULT_ARGUMENT_SHORTNAME,
                                        false,
                                        source.isMultiValued(),
+                                       source.isHidden(),
                                        null );
     }
 
@@ -118,6 +119,7 @@ public class SAMFileWriterArgumentTypeDescriptor extends ArgumentTypeDescriptor
                                        false,
                                        false,
                                        false,
+                                       source.isHidden(),
                                        null,
                                        null,
                                        null );

java/src/org/broadinstitute/sting/gatk/walkers/Hidden.java

@@ -0,0 +1,40 @@
+/*
+ * Copyright (c) 2010, The Broad Institute
+ *
+ * Permission is hereby granted, free of charge, to any person
+ * obtaining a copy of this software and associated documentation
+ * files (the "Software"), to deal in the Software without
+ * restriction, including without limitation the rights to use,
+ * copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the
+ * Software is furnished to do so, subject to the following
+ * conditions:
+ *
+ * The above copyright notice and this permission notice shall be
+ * included in all copies or substantial portions of the Software.
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+ * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
+ * OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+ * NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
+ * HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+ * WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+ * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
+ * OTHER DEALINGS IN THE SOFTWARE.
+ */
+
+package org.broadinstitute.sting.gatk.walkers;
+
+import java.lang.annotation.*;
+
+/**
+ * Indicates that a walker or walker argument should not be presented in the help system.
+ *
+ * @author mhanna
+ * @version 0.1
+ */
+@Documented
+@Inherited
+@Retention(RetentionPolicy.RUNTIME)
+@Target({ElementType.TYPE,ElementType.FIELD})
+public @interface Hidden {
+}

java/src/org/broadinstitute/sting/utils/help/HelpFormatter.java

@@ -89,6 +89,8 @@ public class HelpFormatter {
 
         for( ArgumentDefinitionGroup argumentGroup: argumentGroups ) {
             for( ArgumentDefinition argumentDefinition: argumentGroup.argumentDefinitions ) {
+                if(argumentDefinition.isHidden)
+                    continue;
                 lineFormatter.format(" ");
                 if( !argumentDefinition.required ) lineFormatter.format("[");
                 if( argumentDefinition.shortName != null )
@@ -125,24 +127,33 @@ public class HelpFormatter {
     private String getDetailed( List<ArgumentDefinitionGroup> argumentGroups ) {
         StringBuilder builder = new StringBuilder();
 
-        for( ArgumentDefinitionGroup argumentGroup: argumentGroups ) {
+        for( ArgumentDefinitionGroup argumentGroup: argumentGroups )
-            if( argumentGroup.groupName != null && argumentGroup.argumentDefinitions.size() != 0 )
+            builder.append( getDetailForGroup( argumentGroup ) );
-                builder.append( String.format("%nArguments for %s:%n", argumentGroup.groupName ) );
-            builder.append( getDetailForGroup( argumentGroup.argumentDefinitions ) );
-        }
 
         return builder.toString();
     }
 
     /**
      * Gets a detailed description for a given argument group.
-     * @param argumentDefinitions The argument definitions contained withina group.
+     * @param argumentDefinitionGroup The group of argument definitions to render.
      * @return A string giving detailed info about the contents of this group.
      */
-    private String getDetailForGroup( List<ArgumentDefinition> argumentDefinitions ) {
+    private String getDetailForGroup( ArgumentDefinitionGroup argumentDefinitionGroup ) {
+        if(argumentDefinitionGroup.allHidden())
+            return "";
+
         StringBuilder builder = new StringBuilder();
         Formatter formatter = new Formatter( builder );
 
+        if( argumentDefinitionGroup.groupName != null && argumentDefinitionGroup.argumentDefinitions.size() != 0 )
+            builder.append( String.format("%nArguments for %s:%n", argumentDefinitionGroup.groupName ) );
+
+        List<ArgumentDefinition> argumentDefinitions = new ArrayList<ArgumentDefinition>();
+        for(ArgumentDefinition argumentDefinition: argumentDefinitionGroup.argumentDefinitions) {
+            if(!argumentDefinition.isHidden)
+                argumentDefinitions.add(argumentDefinition);
+        }
+
         // Try to fit the entire argument definition across the screen, but impose an arbitrary cap of 3/4 *
         // LINE_WIDTH in case the length of the arguments gets out of control.
         int argWidth = Math.min( findLongestArgumentCallingInfo(argumentDefinitions), (TextFormattingUtils.DEFAULT_LINE_WIDTH*3)/4 - FIELD_SEPARATION_WIDTH );