Package readycli

Class Command.Builder

java.lang.Object
readycli.Command.Builder
Enclosing class:
Command
public static class Command.Builder
extends java.lang.Object
Class used to build a new command. To instantiate this class use the Command.create(String, String, String...) method.
Author:
Salvatore Giampa'

  • Method Details

    • addDocumentationAlias

      public Command.Builder addDocumentationAlias​(java.lang.String alias)
      Adds a new alias for the option that shows the documentation. This option must be found on the first element of the arguments list. In other cases it is interpreted as an argument for the command execution.
      Parameters:
      alias - the alias for the documentation command
      Returns:
      this same builder
      Throws:
      java.lang.IllegalStateException - if the given name is already assigned to a required argument, option, sub-command, documentation alias or if the command has been already built.
      See Also:
      addDocumentationAliases(String...)

    • addDocumentationAliases

      public Command.Builder addDocumentationAliases​(java.lang.String... aliases)
      Adds new aliases for the documentation option, that shows the documentation. This option must be found on the first element of the arguments list. In other cases it is interpreted as an argument for the command execution.
      Parameters:
      aliases - the aliases for the documentation option.
      Returns:
      this same builder
      Throws:
      java.lang.IllegalStateException - if the given name is already assigned to a required argument, option, sub-command, documentation alias or if the command has been already built.
      See Also:
      addDocumentationAlias(String)

    • addRequiredArgument

      public Command.Builder addRequiredArgument​(java.lang.String name, java.lang.String description) throws java.lang.IllegalStateException
      Adds a required argument to the command. This method maintains the order of addiction of the required arguments. That order is then used to receive arguments on the command-line.
      Parameters:
      name - the name of the argument.
      description - the description of the argument.
      Returns:
      this same builder
      Throws:
      java.lang.IllegalStateException - if the given name is already assigned to a required argument, option, sub-command, documentation alias or if the command has been already built.

    • addFlag

      public Command.Builder addFlag​(java.lang.String name, java.lang.String description) throws java.lang.IllegalStateException
      Adds a flag to the command. A flag is a normal option with no parameters. The flag boolean value is accessed by using a CommandContext as a normal Option, and using the method OptionValues.getFlag(). This method is used to automate the creation of an option with no parameters and invoking it has the same effect of invoking the addOption(Option) on a new option with no parameters:

      addOption(Option.create(name, description).build());
      Parameters:
      name - the name of the flag.
      description - the description of the flag.
      Returns:
      this same builder
      Throws:
      java.lang.IllegalStateException - if the given name is already assigned to a required argument, sub-command, documentation alias or if the command has been already built.

    • addOption

      public Command.Builder addOption​(Option option) throws java.lang.IllegalStateException
      Adds an option to the command. An Option has a name that starts with a lowercase or a capital letter. The name specified at the option construction is then used to access it from the CommandContext. The option can be specified on the command-line by using "--" followed by the option name or "-" followed by an option alias.
      Parameters:
      option - the option to add.
      Returns:
      this same builder
      Throws:
      java.lang.IllegalStateException - if the name of the given option is already assigned to a required argument, option, sub-command, documentation alias or if the command has been already built.

    • addSubCommand

      public Command.Builder addSubCommand​(java.lang.String name, Command subCommand) throws java.lang.IllegalStateException
      Adds a sub-command that can be invoked by specifying it as the first argument of the current command. Basically, This method allows for nested commands definition. The added sub-command can expose other sub-commands that are sub-commands of second level respect to the current command, and these can expose other sub-commands that are sub-commands of third level respect to the current command, and so on.
      Parameters:
      name - the name used to invoke the sub-command
      subCommand - the sub-command to add.
      Returns:
      this same builder
      Throws:
      java.lang.IllegalStateException - if the name of the given sub-command is already assigned to a required argument, option, sub-command, documentation alias or if the command has been already built.

    • build

      public Command build​(CommandExecutor commandExecutor)
      Builds the new command. To build a command, a CommandExecutor is required. The CommandExecutor receives the arguments and the options parsed on the command-line in a CommandContext object and it represents the actions of the command. If the given CommandExecutor is null, then invoking the command without giving a sub-command will output an error and the execute method of the command will return the Command.ExitCause.ERROR_COMMAND_NOT_IMPLEMENTED value. Executing the command documentation, indicating '?' as first argument, will return the list of sub-commands only, ignoring arguments and options.

      Hint: a CommandExecutor can just collect the values of the arguments and the options in an opportune data-structure or in the fields of an object that can be queried by the application, doing the type casting or the parsing of these string values received from the command-line.
      Parameters:
      commandExecutor - the CommandExecutor that does the actions associated to this command. It can be null.
      Returns:
      the new command.