Package readycli

Class Command

java.lang.Object
readycli.Command
All Implemented Interfaces:
java.io.Serializable
public final class Command
extends java.lang.Object
implements java.io.Serializable
Represents a command to be typed in a command line. The command can be included in a CLI or can be a stand-alone command that represents a Java class with an executable main() method. In this case the command can be used to parse command line arguments passed to the main() method.

Command components

A command is mainly composed by:
  • A usage string: shows how to use the command;
  • A description: is used for command documentation; it tells what the command will do when invoked;
  • Required arguments: are the arguments necessary for command execution (e.g. the source and the destination file names for a copy command).
  • Options: optional parameters or flags that have a changeable default values (e.g. a parameter that indicates the name of a log file, or a flag that tells if the source file must be deleted after a copy)
  • Sub-commands: are commands nested in the current one. Invoking a sub-command is equivalent to invoke another independent command with the simple difference that its first level name is the current one.
  • Documentation option: is the optional flag that shows the documentation of the command. The documentation option can have more than one alias. An alias for the documentation option is a simple name string that can be typed by the user as first argument of the command to show its documentation.

Usage String

The usage string show how to use the command. For example: given a class my.example.Main with a main() method that implements the command, the usage string is an information for the user that tells how to run the program, showing that the user must run the java command, followed by a class-path and by the canonical name of the class that contains the main method. In this case the usage string can be
java -cp MyExample/classes my.example.Main
If the program is designed to run from a jar file, the usage string can specify to run the program as
java -jar myjarfile.jar
Alternatively, the usage string can be an empty string, so that documentation shows only the expected arguments.
If the command is implemented in a CLI, the usage string can be just equal to the name of the command.
The usage string can be an empty string.

Required Arguments

All the required arguments must be typed just as first arguments for the command, in the same order they are specified during command construction and in the documentation.

Options

For details about the options see Option.

Sub-commands

A sub-command is just a command that can be used by typing its name after the name of the current one. The sub-command will have its own required arguments, options, sub-commands and documentation option.

Documentation option

As said above, the documentation option can have one or more aliases, to be typed by the final user of the software. If the developer does not indicate a documentation option alias during the command construction, the command will not have documentation option available. The developer should always indicate one or more documentation option aliases using the Command.Builder.addDocumentationAlias(String) method or Command.Builder.addDocumentationAliases(String...) method.

Author:
Salvatore Giampa'
See Also:
Serialized Form

  • Nested Class Summary

    Nested Classes 
    Modifier and Type Class Description
    static class  Command.Builder
    Class used to build a new command.
    static class  Command.ExitCause
    Specify the cause of the exit from command execution.

  • Method Summary

    Modifier and Type Method Description
    static Command.Builder create​(java.lang.String usageString, java.lang.String description, java.lang.String... docAliases)
    Creates a new command with the given name, description, usage string and documentation option aliases.

    See Command for more details about usage strings.
    static Command.Builder defaultDocs​(java.lang.String usageString, java.lang.String description)
    Creates a new command with the given name, description, usage string and with the default documentation option aliases, that are '?'
    Command.ExitCause execute​(java.lang.String arguments)
    Executes the command on a list of arguments encoded as a string command-line, as execute(String, PrintStream, InputStream), and uses the standard in/output to interact with the user.
    Command.ExitCause execute​(java.lang.String[] args)
    Executes the command on an array of arguments already tokenized, using the standard I/O to interact with the user.
    Command.ExitCause execute​(java.lang.String[] args, java.io.PrintStream output, java.io.InputStream input)
    Executes the command on an array of arguments already tokenized.
    Command.ExitCause execute​(java.lang.String arguments, java.io.PrintStream output, java.io.InputStream input)
    Executes the command on a list of arguments encoded as a string command-line.

    This method automatically splits the command-line taking care of single quote ('), double quote (") and escaped characters, as a UNIX-like operative system does, then it passes the result list of arguments to the execute(List, PrintStream, InputStream) method

    Single quotes (') and double quotes (") characters can be escaped preceding them with a backslash (\) character: \", \'.
    The backslash (\) character can be escaped itself in the same way: \\.

    Note that: the first token of the passed command-line is parsed as an argument of the command and not as the name of the command itself.
    Command.ExitCause execute​(java.util.List<java.lang.String> arguments)
    Executes the command on a list of arguments already tokenized, using the standard I/O to interact with the user.

    For more details, please refer to execute(List, PrintStream, InputStream);
    Command.ExitCause execute​(java.util.List<java.lang.String> arguments, java.io.PrintStream output, java.io.InputStream input)
    Executes the command on a list of arguments already tokenized.

    Note that: the first token is parsed as an argument of the command and not as the name of the command itself.
    java.lang.String getDescription()
    Gets the command description.
    java.util.Set<java.lang.String> getDocumentationAliases()  
    java.util.Map<java.lang.String,​Option> getOptions()
    Gets a map of all the options of this command.
    java.util.List<readycli.RequiredArgument> getRequiredArguments()
    Gets the list of all the required arguments of this command.
    java.util.Map<java.lang.String,​Command> getSubCommands()
    Gets a map of all the sub-commands of first level of this command.

    Methods inherited from class java.lang.Object

    equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

  • Method Details

    • create

      public static Command.Builder create​(java.lang.String usageString, java.lang.String description, java.lang.String... docAliases)
      Creates a new command with the given name, description, usage string and documentation option aliases.

      See Command for more details about usage strings.
      Parameters:
      usageString - the string that specify how to run the command
      description - the human-readable description of the command
      docAliases - the aliases for the documentation option
      Returns:
      a new Command.Builder
      See Also:
      Command, defaultDocs(String, String)

    • defaultDocs

      public static Command.Builder defaultDocs​(java.lang.String usageString, java.lang.String description)
      Creates a new command with the given name, description, usage string and with the default documentation option aliases, that are '?', '-h' and '--help'.

      See Command for more details about usage strings.
      Parameters:
      usageString - the string that specify how to run the command
      description - the human-readable description of the command
      Returns:
      a new Command.Builder
      See Also:
      Command

    • getDescription

      public java.lang.String getDescription()
      Gets the command description.
      Returns:
      the description as string.

    • getRequiredArguments

      public java.util.List<readycli.RequiredArgument> getRequiredArguments()
      Gets the list of all the required arguments of this command.
      Returns:
      an unmodifiable list.

    • getOptions

      public java.util.Map<java.lang.String,​Option> getOptions()
      Gets a map of all the options of this command.
      Returns:
      an unmodifiable map that associates the names of the options (keys) to the options themselves (values).

    • getSubCommands

      public java.util.Map<java.lang.String,​Command> getSubCommands()
      Gets a map of all the sub-commands of first level of this command.
      Returns:
      an unmodifiable map that associates the names of the sub-commands (keys) to the sub-commands themselves (values).

    • getDocumentationAliases

      public java.util.Set<java.lang.String> getDocumentationAliases()

    • execute

      public Command.ExitCause execute​(java.lang.String arguments)
      Executes the command on a list of arguments encoded as a string command-line, as execute(String, PrintStream, InputStream), and uses the standard in/output to interact with the user.
      Parameters:
      arguments - the command-line arguments for this command as a full string
      Returns:
      the exit cause
      See Also:
      execute(String, PrintStream, InputStream)

    • execute

      public Command.ExitCause execute​(java.lang.String arguments, java.io.PrintStream output, java.io.InputStream input)
      Executes the command on a list of arguments encoded as a string command-line.

      This method automatically splits the command-line taking care of single quote ('), double quote (") and escaped characters, as a UNIX-like operative system does, then it passes the result list of arguments to the execute(List, PrintStream, InputStream) method

      Single quotes (') and double quotes (") characters can be escaped preceding them with a backslash (\) character: \", \'.
      The backslash (\) character can be escaped itself in the same way: \\.

      Note that: the first token of the passed command-line is parsed as an argument of the command and not as the name of the command itself. If the command-line comprises the name of this command, the caller should separate the name of this command from its arguments before invoking this method.
      Parameters:
      arguments - the command-line arguments for this command as a full string
      output - the output stream to write messages for the user to.
      input - the input stream used to read the user input.
      Returns:
      the exit cause

    • execute

      public Command.ExitCause execute​(java.lang.String[] args)
      Executes the command on an array of arguments already tokenized, using the standard I/O to interact with the user. This method is useful to be invoked on the arguments received by the main() method.

      For more details, please refer to execute(List, PrintStream, InputStream);
      Parameters:
      args - the command-line arguments for this command as an array of strings
      Returns:
      the exit cause

    • execute

      public Command.ExitCause execute​(java.lang.String[] args, java.io.PrintStream output, java.io.InputStream input)
      Executes the command on an array of arguments already tokenized. This method is useful to be invoked on the arguments received by the main() method.

      For more details, please refer to execute(List, PrintStream, InputStream);
      Parameters:
      args - the command-line arguments for this command as an array of strings
      output - the output stream to write messages for the user to.
      input - the in stream used to read the user in.
      Returns:
      the exit cause

    • execute

      public Command.ExitCause execute​(java.util.List<java.lang.String> arguments)
      Executes the command on a list of arguments already tokenized, using the standard I/O to interact with the user.

      For more details, please refer to execute(List, PrintStream, InputStream);
      Parameters:
      arguments - the list of arguments
      Returns:
      the exit cause
      See Also:
      execute(List, PrintStream, InputStream)

    • execute

      public Command.ExitCause execute​(java.util.List<java.lang.String> arguments, java.io.PrintStream output, java.io.InputStream input)
      Executes the command on a list of arguments already tokenized.

      Note that: the first token is parsed as an argument of the command and not as the name of the command itself. The caller should separate the name of this command from its arguments before invoking this method.
      Parameters:
      arguments - the command-line arguments already for this command as a list of strings
      output - the output stream to write messages for the user to.
      input - the in stream used to read the user in.
      Returns:
      the exit cause