Package 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 (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 `Option`s 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
`SubCommandHandler​(CmdLineParser parser, OptionDef option, Setter<java.lang.Object> setter)`

### Method Summary

All Methods Instance Methods Concrete Methods
`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.
`java.lang.String` `getMetaVariable​(java.util.ResourceBundle rb)`
`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

`getNameAndMeta, getNameAndMeta, print, printDefaultValue`

### 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, returns `0` if this option doesn't take any parameters.)
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. The value returned by this method can be a reference in the `ResourceBundle`, if one was passed to `CmdLineParser`.

Specified by:
  `getDefaultMetaVariable` in class `OptionHandler<java.lang.Object>`
Returns:
  `null` to hide a meta variable.

#### getMetaVariable

    public java.lang.String getMetaVariable​(java.util.ResourceBundle rb)

Overrides:
  `getMetaVariable` in class `OptionHandler<java.lang.Object>`