Package org.kohsuke.args4j.spi

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

    • 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

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