Re: [cli] Suggestions

[Martin Redington]

Hi John,

   thanks for your reply,

Check out this unit test which shows how to use typed options:
http://cvs.apache.org/viewcvs.cgi/jakarta-commons/cli/src/test/org/ apache/commons/cli/PatternOptionBuilderTest.java?rev=1.6&content- type=text/vnd.viewcvs-markup

2. Options can have a long name and no short name (flag). This is handy for when you have a lot of parameters, and run out of suitable short names.

This is possible in CLI, e.g. OptionBuilder.withLongOpt( "username" ).hasArg().create().

It seems quite awkward (IMHO) to chain together all of those method calls. I got round this with method overloading.

I have a *lot* of constructors/factory methods in my lib, but there is a simple set of rules that lets you determine what to write, so that constructors work in a very concise, DWIM (do what I mean) fashion.

My base constructor is

/**
* @param name The long name for the option.
* @param flag The flag for the option.
* @param argument A constant value indicating whether an argument is not allowed/optional/required
* @param defaultValue An object containing the default value
* @param type A constant value indicating the type (boolean, string, int or double) of the object
* @param argName A string to use for the argument in usage messages (e.g., filename).
* @param description A description of the option.
*/
Option(String name, char flag, int argument, Object defaultValue, int type, String argName, String description);

The rules for other constructors.

An option must have a name and/or a flag.
argument is optional (for boolean options, there is no argument, otherwise required argument is assumed)
defaultValue/type are replaced by a single boolean, String, int or double value, which indicates the default value and the type of the option.
argName and description are optional.

That generates a lot of constructors in the library (I think I could make argName optional as well---right now you either have to have argName and description as well, or neither---which would add a lot more constructors).

However, the constructors are pretty unambiguous to the end-user, so the library ends up being very easy to use. For example, see the code below.

CommandLineOptions options = new CommandLineOptions();

try{
options.addCommandLineOption("url", 'u', DEFAULT_URL_STRING);
options.addCommandLineOption("method", 'm', "");
options.addCommandLineOption("secure", 's', false);
options.addCommandLineOption("help", 'h', false);

int lastArg = options.parseCommandLine("TestClient", args);

url = options.stringValue("url");
method = options.stringValue("method");
secure = options.booleanValue("secure");
if(options.booleanValue("help")) options.printUsage(System.out);
}
catch(CommandLineOptionException e){
e.printStackTrace();
}

I don't know whether any scheme like this could be added to CLI at this point, but I think it makes things a lot more friendly for the end-user.

3. Sets of options can be read from and written to properties files.

No support for this.  I have a TODO for myself (I must document it) to
have an XML reader and writer for configuring an Options instance.  I
will document this TODO and also add yours.  If you feel like having a
bash at the properties one that would be cool ;)

Maybe early next week. I should be able to port mine across pretty easily.

4. A set of default options is provided (disabled by default) that will read properties files during parsing, and write them once parsing is completed.

For example:

mycommand --properies-file in.properties --some-other-argument some_value --write-properties-file out.properties

reads option values from in.properties, over-rides the value for --some-other-argument, and dumps the properties out to >> out.properties.

The "special" property options names and flags can be fully customised via method calls.

Might be that I'm a bit sleepy but I don't see what this achieves. Can you
enlighten me please.

sure.

imagine my code looks like

options = myCreateOptions();
options.setUsePropertiesOptions(true);
options.parseCommandLine("mycommand", args);
interrogateOptions(options);

Calling setUsePropertiesOptions with a true argument means that in addition to the options that I defined, my commandline parsing will also support a predefined set of options relating to properties, which support reading option values in from a properties file, and writing options out to a properties file, and specifying a prefix to add to/subtract from property names.

This can be very useful if you have a *lot* of command-line options. I have some simulation apps that run like this. Of course one could argue that if you have so many options, you should be using a properties file or some other mechanism anyway, but this approach lets you have the best of both worlds ... specification of options in a properties file, over-rideable from the command line.

so, for example

runApp --write-properties-file propertiesfile

dumps out all of the options, and their default values into a properties file.

I can now go in and edit this to set a particular set of properties that I want to run

Now I can rerun the program using my edited properties file to configure the application:

runApp --properties-file propertiesfile

Now, if I want to use this properties file as a base, but to override some of the values, I can run

runApp --properties-file propertiesfile --some-other-option newvalue

Of course, you may not like those particular option names, so my class provides methods to let you set the name and flags that will be used for each of these options. Of course, the programmer could implement this themselves, on top of CLI, but this way they get it for free (if they choose to turn it on).

Does that make more sense?

5. During interrogation, option values are retrieved via booleanValue, stringValue, etc. calls. These are "type-safe", in that trying to retrieve a boolean value from an integer option will throw a runtime-exception, which will be thrown the first time that the program is run
(assuming, reasonably that you go through a create/parse/query phase early in program initialisation).

The TypeHandler class does provide support for this at the interrogation
stage. Have a look at it and tell me if there is anything you think is
missing.

I'll check it out ...

I am pretty sure that most of this functionality could be added to CLI without breaking the existing interfaces, and may be useful for some people (not requiring a flag for each option, simple typing, and the properties file functionality has been very handy for me).

If anyone is interested in this, mail me directly for further info. I'd be happy to write patches if people think its a good idea.

I'm glad you found CLI Martin, saves creating another package ;) Let me know if you
have any other queries/comments.

BTW, this is the first time I have seen Davids mail as well.

I just had a very quick squint through the archives ... to see if anyone had suggested this stuff before ...

cheers,
m.



--
To unsubscribe, e-mail: <mailto:commons-dev-unsubscribe@;jakarta.apache.org>
For additional commands, e-mail: <mailto:commons-dev-help@;jakarta.apache.org>