org.kohsuke.args4j.spi

Class SubCommandHandler

java.lang.Object

org.kohsuke.args4j.spi.OptionHandler<java.lang.Object>

org.kohsuke.args4j.spi.SubCommandHandler

public class SubCommandHandler
extends OptionHandler<java.lang.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 (and are 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 {
      @Argument(handler=SubCommandHandler.class)
      @SubCommands({
          @SubCommand(name="checkout",CheckoutCommand.class),
          @SubCommand(name="commit",CommitCommand.class),
          ...
      })
      Command cmd;

      @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 {
     @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

Field Summary

Fields inherited from class org.kohsuke.args4j.spi.OptionHandler

option, owner, setter

Constructor Summary

Constructors

Constructor and Description
SubCommandHandler(CmdLineParser parser, OptionDef option, Setter<java.lang.Object> setter)

Method Summary

Methods

Modifier and Type	Method and Description
protected CmdLineParser	configureParser(java.lang.Object subCmd, SubCommand c)
protected int	fallback(java.lang.String subCmd)
java.lang.String	getDefaultMetaVariable() Gets the default meta variable name used to print the usage screen.
protected java.lang.Object	instantiate(SubCommand c)
int	parseArguments(Parameters params) Called if the option that this owner recognizes is found.
protected java.lang.Object	subCommand(SubCommand c, Parameters params)

Methods inherited from class org.kohsuke.args4j.spi.OptionHandler

getMetaVariable, getNameAndMeta

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

SubCommandHandler

public SubCommandHandler(CmdLineParser parser,
                 OptionDef option,
                 Setter<java.lang.Object> setter)

Method Detail

parseArguments

public int parseArguments(Parameters params)
                   throws CmdLineException

Description copied from class: OptionHandler

Called if the option that this owner recognizes is found.

Specified by:

parseArguments in class OptionHandler<java.lang.Object>

Parameters:

params - The rest of the arguments. This method can use this object to access the arguments of the option if necessary. The object is valid only during the method call.

Returns:

The number of arguments consumed. For example, return 0 if this option doesn't take any parameter.

Throws:

CmdLineException

fallback

protected int fallback(java.lang.String subCmd)
                throws CmdLineException

Throws:

CmdLineException

subCommand

protected java.lang.Object subCommand(SubCommand c,
                          Parameters params)
                               throws CmdLineException

Throws:

CmdLineException

configureParser

protected CmdLineParser configureParser(java.lang.Object subCmd,
                            SubCommand c)

instantiate

protected java.lang.Object instantiate(SubCommand c)

getDefaultMetaVariable

public java.lang.String getDefaultMetaVariable()

Description copied from class: OptionHandler

Gets the default meta variable name used to print the usage screen.

Specified by:

getDefaultMetaVariable in class OptionHandler<java.lang.Object>

Returns:

null to hide a meta variable.