----- Original Message -----
From: "John Keyes" <[EMAIL PROTECTED]>
To: "Jakarta Commons Developers List" <[EMAIL PROTECTED]>
Sent: Wednesday, June 11, 2003 12:24 AM
Subject: Re: [CLI] Support for CVS style command line
...
> >
> > OptionsMap optionsMap = new OptionsMap();
> >
> > // checkout command
> > optionsMap.add("checkout", checkoutOptions);
> > optionsMap.add("co", checkoutOptions);
> > optionsMap.add("get", checkoutOptions);
> >
> > // commit command
> > optionsMap.add("commit", commitOptions);
> > optionsMap.add("ci", commitOptions);
> > optionsMap.add("com", commitOptions);
> >
> > // ...
> >
> > It seems to me that this is losing information as to which commands
> > are the preferred name and which are the synonyms. From a
> > generated help point of view this is useful information and it also
> > doesn't allow for descriptions to be attached to the different
> > commands.
> I agree with your point regarding losing information. I don't think
> associating
> descriptions with each alias is a good idea. I think only one alias
> should be
> displayed in the help, it would be up to the user doc to specify the
> rest.
But the scheme above still doesn't make it clear which alias should be displayed
>
> > Instead of this approach I would suggest something along the following
> > lines:
> > (Note this is just design phase talk, I haven't tried to implement
> > this at all but will be happy to muck in. Presumably using a new
> > Command class but I'm not sure how it fits with AnonymousArgument yet)
> >
> > Each separate command should get it's own Option.
> >
> > checkoutCommand = cbuilder
> > .withOptions(checkoutOptions) // enter the suboptions once
> > .addAlias("co") // add as many alias / synonyms as needed
> > .addAlias("get")
> > .withDescription("Checks out a new working copy") // add some
> > help text
> > .create("checkout")); // add the preferred name of the command
> >
> > checkinCommand = cbuilder
> > .withOptions(checkinOptions) // enter the suboptions once
> > .addAlias("ci") // add as many alias / synonyms as needed
> > .addAlias("com")
> > .withDescription("Sends local changes to the server") // add
> > some help text
> > .create("commit")); // add the preferred name of the command
> >
> > ...
>
> I think the help should only print the "checkout" and "commit" and not
> worry
> about the aliases.
The stage here is purely concerned with knowing which strings identify the same
commands, the fact that it allows aliases to be
displayed in the help is purely a side effect. Personally though its a side effect I
like and I aim to have a HelpFormatter that is
configurable enough to move the choice to the application developer anyway.
>
> > To achieve CVS style operation these should be added to an exclusive
> > group, but its possible that commands could be used in an
> > inclusive manner too.
> >
> > Set commands = new HashSet();
> > commands.add(checkoutCommand);
> > commands.add(checkinCommand);
> > ...
> > options.addOptionGroup(commands);
> >
> > The previous proposal seemed to be targetting a usage line of:
> > cvs [options] command [command-options]
> > But the structure described above should allow something like:
> > cvs [options] checkout | commit | ...
>
> I think the second style has too much information. For the case of
> CVS, it would be
> very very long.
This is true and, at least in my copy of cvs, no attempt is made to print out the
expended usage information. Instead it uses the
cop out of a fixed string.
Usage: cvs [cvs-options] command [command-options-and-arguments]
Maybe we could have the HelpFormatter automatically switching to cop out mode when
there are too many options to display on a single
line. This might detect that there isn't enough room to display all of a group and
reverting to just the group name instead. For
now though I like the CLI v1 approach of letting the developer supply a fixed string
instead of generating one if they wish.
> I need to think a bit more about this, there could be
> a special built
> in option e.g. cvs --help-commands. This produces the list of
> commands and their
> descriptions.
-1. In the CLI engine we don't force "--help" to display the help screen and we
shouldn't be forcing any other options either.
Offering such features as part of any off-the-shelf introspection based configurations
would probably be a good thing though.
Eitherway the implementation should be a simple case of setting a few attributes on
the HelpFormatter and supplying an alternate
Options object:
if(commandLine.hasOption("--help-commands")){
// don't descend into suboptions
helpFormatter.setDepth(0);
// make sure aliases are displayed.
helpFormatter.setDisplayCommandAlias(true);
// display command help
helpFormatter.printHelp(commandsGroup.getOptions());
}
else if(commandLine.hasOption("--help")){
// display full help
helpFormatter.printHelp(allOptions);
}
Of course this is based on my local HelpFormatter implementation; once it does a
little more I'll submit it for inclusion.
Rob
---------------------------------------------------------------------
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
