[CLI] Auto Usage Help issues?

["Hope, Matthew" <Ma...@capitalone.com>]

Have just started using this, excellent tool very easy to use.
However the auto usage stuff seems to need some work.

I have one wish list entry for ordering of arguments.
I have two issues with the auto usage help when using OptionGroups

1) be able to define the order in which options, and option groups are
printed.
Simply using the order in which the options are added to the Options object
would be sufficient to make it work how most people would expect.

2) Option groups don't display the arg name if they exist (and are required)
[-a | -b] instead of [-a foo| -b bar] as I would expect.
The code doing this is explicitly writing it's own info rather than using
the toString() method to get it to achieve consistency.

I would prefer the second format for consistency but accept this may be
personal preference. I would be willing to make this change myself (though
I've never contributed to an OS project before)

3) probably a bug

import org.apache.commons.cli.*;

public class BugTest
{

private final static char SOURCE_ARG = 's';
private final static String SOURCE_LONG_ARG = "source";
private final static char DEST_ARG = 'd';
private final static String DEST_LONG_ARG = "dest";
private final static char TABLE_ARG = 't';
private final static String TABLE_LONG_ARG = "table";
private final static char SCRIPT_ARG = 'f';
private final static String SCRIPT_LONG_ARG = "script";
private static final String CONTROL_FILE_NAME = "control.xml";

public static void main(String[] args) throws Exception
{
	Options options = new Options();
	options.addOption(OptionBuilder.withArgName("dest_db")
			.withDescription("use name as defined in " +
CONTROL_FILE_NAME)
			.isRequired()
			.hasArg()
			.withLongOpt(DEST_LONG_ARG)
			.create(DEST_ARG));
	options.addOption(OptionBuilder.withArgName("source_db")
			.withDescription("use name as defined in " +
CONTROL_FILE_NAME)
			.isRequired()
			.hasArg()
			.withLongOpt(SOURCE_LONG_ARG)
			.create(SOURCE_ARG));
	OptionGroup tableGroup = new OptionGroup();
	tableGroup.isRequired();
	tableGroup.addOption(OptionBuilder.withArgName("table_name")
			.withDescription("same name will be used in source
and dest")
			.hasArg()
			.withLongOpt(TABLE_LONG_ARG)
			.create(TABLE_ARG));
	tableGroup.addOption(OptionBuilder.withArgName("script_file")
			.withDescription("flat text file with 1 tablename
per line")
			.hasArg()
			.withLongOpt(SCRIPT_LONG_ARG)
			.create(SCRIPT_ARG));
	options.addOptionGroup(tableGroup);
	HelpFormatter formatter = new HelpFormatter();
	formatter.printHelp("test", options, true);
}
}

Produces usage info of form

usage: test -d dest_db [-t | -f]-s source_db [-f script_file]
-d,--dest <dest_db>         use name as defined in control.xml
-f,--script <script_file>   flat text file with 1 tablename per line
-s,--source <source_db>     use name as defined in control.xml
-t,--table <table_name>     same name will be used in source and dest 

For some reason the second member of the optionGroup is printed both in and
out of the group...
I'm using the 1.0 release.

I would be happy to (attempt to) change all of the above, but am I confess
unused to actually changing open source projects and feeding those changes
back in (if they are wanted)

Matt Hope

 
**************************************************************************
The information transmitted herewith is sensitive information intended only
for use by the individual or entity to which it is addressed. If the reader
of this message is not the intended recipient, you are hereby notified that
any review, retransmission, dissemination, distribution, copying or other
use of, or taking of any action in reliance upon this information is
strictly prohibited. If you have received this communication in error,
please contact the sender and delete the material from your computer.

Re: [CLI] Auto Usage Help issues?

[John Keyes <jb...@mac.com>]

Hi Matt,

> Have just started using this, excellent tool very easy to use.
Thanks.

> However the auto usage stuff seems to need some work.
> I have one wish list entry for ordering of arguments.
> I have two issues with the auto usage help when using OptionGroups
> 
> 1) be able to define the order in which options, and option groups are
> printed.
> Simply using the order in which the options are added to the Options object
> would be sufficient to make it work how most people would expect.
This should be made configurable alright.

> 2) Option groups don't display the arg name if they exist (and are required)
> [-a | -b] instead of [-a foo| -b bar] as I would expect.
> The code doing this is explicitly writing it's own info rather than using
> the toString() method to get it to achieve consistency.
> 
> I would prefer the second format for consistency but accept this may be
> personal preference. I would be willing to make this change myself (though
> I've never contributed to an OS project before)
I suppose that makes it dependent on the implementation of toString(),
and would raise the question about how much information we want in
the toString method.  I think this should be a dump of all information
from the Option and one specifically formatted for display.  The
addition of a getUsage and getHelp methods would be helpful though.

> 3) probably a bug
> 
> import org.apache.commons.cli.*;
> 
> public class BugTest
> {
> 
> private final static char SOURCE_ARG = 's';
> private final static String SOURCE_LONG_ARG = "source";
> private final static char DEST_ARG = 'd';
> private final static String DEST_LONG_ARG = "dest";
> private final static char TABLE_ARG = 't';
> private final static String TABLE_LONG_ARG = "table";
> private final static char SCRIPT_ARG = 'f';
> private final static String SCRIPT_LONG_ARG = "script";
> private static final String CONTROL_FILE_NAME = "control.xml";
> 
> public static void main(String[] args) throws Exception
> {
> 	Options options = new Options();
> 	options.addOption(OptionBuilder.withArgName("dest_db")
> 			.withDescription("use name as defined in " +
> CONTROL_FILE_NAME)
> 			.isRequired()
> 			.hasArg()
> 			.withLongOpt(DEST_LONG_ARG)
> 			.create(DEST_ARG));
> 	options.addOption(OptionBuilder.withArgName("source_db")
> 			.withDescription("use name as defined in " +
> CONTROL_FILE_NAME)
> 			.isRequired()
> 			.hasArg()
> 			.withLongOpt(SOURCE_LONG_ARG)
> 			.create(SOURCE_ARG));
> 	OptionGroup tableGroup = new OptionGroup();
> 	tableGroup.isRequired();
> 	tableGroup.addOption(OptionBuilder.withArgName("table_name")
> 			.withDescription("same name will be used in source
> and dest")
> 			.hasArg()
> 			.withLongOpt(TABLE_LONG_ARG)
> 			.create(TABLE_ARG));
> 	tableGroup.addOption(OptionBuilder.withArgName("script_file")
> 			.withDescription("flat text file with 1 tablename
> per line")
> 			.hasArg()
> 			.withLongOpt(SCRIPT_LONG_ARG)
> 			.create(SCRIPT_ARG));
> 	options.addOptionGroup(tableGroup);
> 	HelpFormatter formatter = new HelpFormatter();
> 	formatter.printHelp("test", options, true);
> }
> }
> 
> Produces usage info of form
> 
> usage: test -d dest_db [-t | -f]-s source_db [-f script_file]
> -d,--dest <dest_db>         use name as defined in control.xml
> -f,--script <script_file>   flat text file with 1 tablename per line
> -s,--source <source_db>     use name as defined in control.xml
> -t,--table <table_name>     same name will be used in source and dest 
> 
> For some reason the second member of the optionGroup is printed both in and
> out of the group...
> I'm using the 1.0 release.
OK, thats a bug.  

> I would be happy to (attempt to) change all of the above, but am I confess
> unused to actually changing open source projects and feeding those changes
> back in (if they are wanted)
Actually I am currently implementing a v2 of CLI (haven't gotten it into
CVS yet..) and I haven't started work on the HelpFormatter yet, so 
I would say the best thing to do is to leave it with me for the time
being.  I am not sure what the outcome of the v2 work will be, and
whether the v1 will be maintained so when I get a chance I will 
try to sort this out.

Thanks for the feedback,
-John k