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