Class SubCommandHandler

java.lang.Object
org.kohsuke.args4j.spi.OptionHandler<Object>
org.kohsuke.args4j.spi.SubCommandHandler
public class SubCommandHandler extends OptionHandler<Object>
OptionHandler used with Argument for parsing typical "sub-command" pattern.

The "sub-command" pattern refers to the design of the command line like git and svn, where the first argument to the command designates a sub-command (say git checkout), then everything that follows afterward are parsed by this sub-command (which is usually different depending on which sub-command was selected.)

This OptionHandler models this design pattern with the SubCommands annotation. See the following example: 

class Git {
     &#64;Argument(handler={@link SubCommandHandler}.class)
     &#64;SubCommands({
         &#64;SubCommand(name="checkout", impl=CheckoutCommand.class),
         &#64;SubCommand(name="commit", impl=CommitCommand.class),
         ...
     })
     Command cmd;

     &#64;Option(name="-r")
     boolean recursive;

     public static void main(String[] args) {
         Git git = new Git();
         new CmdLineParser(git).parseArgument(args);
         git.cmd.execute();
     }
}

class CheckoutCommand {
    &#64;Option(name="-a")
    boolean all;

    ...
}

An example of legal command line option for this is -r checkout -a.

  • SubCommand only works with Argument and not with Option.
  • The same field/setter must be also annotated with SubCommands that specify possible sub-commands.
  • Any Options that you define in the Git class above can parse options that appear prior to the sub-command name. This is useful for defining global options that work across sub-commands.
  • The matching sub-command implementation gets instantiated with the default constructor, then a new CmdLineParser will be created to parse its annotations.
  • The rest of the arguments that follow the sub-command will be parsed with this new CmdLineParser
  • The fully populated sub-command instance is set as the value.

This class defines a number of protected methods that allow subtypes to customize various parts of the behaviours. This should also serve as an example if you want to combine this with more sophisticated sub-command lookup, such as through META-INF/services, sezpoz, or annotation indexer.

Author:
Kohsuke Kawaguchi