Class SubCommandHandler
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 {
@Argument(handler={@link SubCommandHandler}.class)
@SubCommands({
@SubCommand(name="checkout", impl=CheckoutCommand.class),
@SubCommand(name="commit", impl=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 withArgument
and not withOption
. -
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.
-
Field Summary
FieldsFields inherited from class org.kohsuke.args4j.spi.OptionHandler
option, owner, setter
-
Constructor Summary
ConstructorsConstructorDescriptionSubCommandHandler
(CmdLineParser parser, OptionDef option, Setter<Object> setter) -
Method Summary
Modifier and TypeMethodDescriptionprotected CmdLineParser
configureParser
(Object subCmd, SubCommand c) protected int
Gets the default meta variable name used to print the usage screen.protected Object
int
parseArguments
(Parameters params) Called if the option that this owner recognizes is found.protected Object
subCommand
(SubCommand c, Parameters params) Methods inherited from class org.kohsuke.args4j.spi.OptionHandler
getNameAndMeta, getNameAndMeta, print, printDefaultValue
-
Field Details
-
commands
-
-
Constructor Details
-
SubCommandHandler
-
-
Method Details
-
parseArguments
Description copied from class:OptionHandler
Called if the option that this owner recognizes is found.- Specified by:
parseArguments
in classOptionHandler<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
- Throws:
CmdLineException
-
subCommand
- Throws:
CmdLineException
-
configureParser
-
instantiate
-
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 theResourceBundle
, if one was passed toCmdLineParser
.- Specified by:
getDefaultMetaVariable
in classOptionHandler<Object>
- Returns:
null
to hide a meta variable.
-
getMetaVariable
- Overrides:
getMetaVariable
in classOptionHandler<Object>
-