----- 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]