Module com.github.sttk.cliargs
Package com.github.sttk.cliargs

Class Cmd

java.lang.Object
com.github.sttk.cliargs.Cmd
public class Cmd extends Object
Parses command line arguments and stores them.

The results of parsing are stored by separating into command name, command arguments, options, and option arguments.

  • Constructor Summary

    Constructors
    Constructor
    Description
    Cmd(String name, String... osArgs)
    Constructs an instance of this class with command line arguments.

  • Method Summary

    Modifier and Type
    Method
    Description
    List<String>
    args()
    Returns the command arguments.
    boolean
    hasOpt(String name)
    Checks whether an option with the specified name exists.
    String
    name()
    Returns the command name.
    Optional<String>
    optArg(String name)
    Returns the option argument with the specified name.
    Optional<List<String>>
    optArgs(String name)
    Returns the option arguments with the specified name.
    List<OptCfg>
    optCfgs()
    Returns the option configurations which was used to parse command line arguments.
    void
    parse()
    Parses command line arguments without configurations.
    void
    parseFor(Object optStore)
    Parses command line arguments and set their option values to the fields of the option store which is passed as the argument of this method.
    Optional<Cmd>
    parseUntilSubCmd()
    Parses command line arguments without configurations but stops parsing when encountering first command argument.
    Optional<Cmd>
    parseUntilSubCmdFor(Object optStore)
    Parses command line arguments until the first command argument and set their option values to the option store which is passed as an argument.
    Optional<Cmd>
    parseUntilSubCmdWith(OptCfg[] optCfgs)
    Parses command line arguments with option configurations but stops parsing when encountering first command argument.
    void
    parseWith(OptCfg[] optCfgs)
    Parses command line arguments with option configurations.
    String
    toString()
    Returns a String object representing the content of this object.

    Methods inherited from class java.lang.Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

  • Constructor Details

    • Cmd

      public Cmd(String name, String... osArgs)
      Constructs an instance of this class with command line arguments.
      Parameters:
      name - The command name.
      osArgs - The command line arguments.

  • Method Details

    • name

      public String name()
      Returns the command name.

      This name is the base name extracted from the command path string, which is the first element of the command line arguments.

      Returns:
      The command name.

    • args

      public List<String> args()
      Returns the command arguments.
      Returns:
      The command arguments.

    • hasOpt

      public boolean hasOpt(String name)
      Checks whether an option with the specified name exists.
      Parameters:
      name - The option name.
      Returns:
      True, if the option exists.

    • optArg

      public Optional<String> optArg(String name)
      Returns the option argument with the specified name.

      If the option has multiple arguments, this method returns the first argument. If the option is a boolean flag, this method returns empty of Optional. If the option is not specified in the command line arguments, the return value of this method is empty of Optional.

      Parameters:
      name - The option name.
      Returns:
      An Optional object which may contain the first option argument.

    • optArgs

      public Optional<List<String>> optArgs(String name)
      Returns the option arguments with the specified name.

      If the option has one or multiple arguments, this method returns an array of the arguments. If the option is a boolean flag, this method returns an Optional including an empty list. If the option is not specified in the command line arguments, the return value of this method is empty of Optional.

      Parameters:
      name - The option name.
      Returns:
      An Optional object which may contain the option arguments.

    • optCfgs

      public List<OptCfg> optCfgs()
      Returns the option configurations which was used to parse command line arguments.
      Returns:
      The option configurations.

    • toString

      public String toString()
      Returns a String object representing the content of this object.
      Overrides:
      toString in class Object
      Returns:
      A stirng representation of the content of this object.

    • parse

      public void parse() throws InvalidOption
      Parses command line arguments without configurations.

      This method divides command line arguments into options and command arguments based on simple rules that are almost the same as POSIX & GNU: arguments staring with - or -- are treated as options, and others are treated as command arguments.

      If an = is found within an option, the part before the = is treated as the option name, and the part after the = is treated as the option argument. Options starting with -- are long options and option starting with - are short options. Multiple short options can be concatenated into a single command line argument. If an argument is exactly --, all subsequent arguments are treated as command arguments.

      The results of parsing are stored into this Cmd instance. If it is failed to parsing, a InvalidOption exception is thrown.

      Throws:
      InvalidOption - If failed to parsing command line arguments.

    • parseUntilSubCmd

      public Optional<Cmd> parseUntilSubCmd() throws InvalidOption
      Parses command line arguments without configurations but stops parsing when encountering first command argument. This method creates and returns a new Cmd instance that holds the command line arguments starting from the first command argument. This method parses command line arguments in the same way as the parse() method, except that it only parses the command line arguments before the first command argument.
      Returns:
      A Cmd instance which holds commnd line arguments after a sub command (optional).
      Throws:
      InvalidOption - If failed to parsing command line arguments.

    • parseWith

      public void parseWith(OptCfg[] optCfgs) throws InvalidOption
      Parses command line arguments with option configurations. This method divides command line arguments to command arguments and options. And an option consists of a name and an option argument. Options are divided to long format options and short format options. About long/short format options, since they are same with parse method, see the comment of that method. This method allows only options declared in option configurations, basically. An option configuration has fields: storeKey, names, hasArg, isArray, defaults, desc, argInHelp, and validator. When an option matches one of the names in the option configurations, the option is registered into Cmd with storeKey. If both hasArg and isArray are true, the option can have one or multiple option arguments, and if hasArg is true and isArray is false, the option can have only one option argument, otherwise the option cannot have option arguments. If defaults field is specified and no option value is given in command line arguments, the value of defaults is set as the option arguments. If options not declared in option configurations are given in command line arguments, this method basicaly throws UnconfiguredOption exception. However, if you want to allow other ooptions, add an option configuration of which storeKey or the first element of names is "*". The option configurations used to parsing are set into the Cmd instance, and it can be retrieved with its method: optCfgs().
      Parameters:
      optCfgs - The array of the option configurations.
      Throws:
      InvalidOption - If failed to parsing command line arguments.

    • parseUntilSubCmdWith

      public Optional<Cmd> parseUntilSubCmdWith(OptCfg[] optCfgs) throws InvalidOption
      Parses command line arguments with option configurations but stops parsing when encountering first command argument. This method creates and returns a new Cmd instance that holds the command line arguments starting from the first command argument. This method parses command line arguments in the same way as the parseWith(com.github.sttk.cliargs.OptCfg[]) method, except that it only parses the command line arguments before the first command argument. The option configurations used to parsing are set into the Cmd instance, and it can be retrieved with its method: optCfgs().
      Parameters:
      optCfgs - The array of the option configurations.
      Returns:
      A Cmd instance which holds commnd line arguments after a sub command (optional).
      Throws:
      InvalidOption - If failed to parsing command line arguments.

    • parseFor

      public void parseFor(Object optStore) throws InvalidOption, FailToSetOptionStoreField
      Parses command line arguments and set their option values to the fields of the option store which is passed as the argument of this method.

      This method divides command line arguments to command arguments and options, then sets each option value to a corresponding field of the option store.

      Within this method, an array of OptCfg is made from the fields of the option store. This OptCfg array is set into this Cmd instance. If you want to access this option configurations, get them by optCfgs() method.

      An option configuration corresponding to each field of an option store is determined by its type and Opt field annotation. If the type is bool, the option takes no argument. If the type is integer, floating point number or string, the option can takes single option argument, therefore it can appear once in command line arguments. If the type is an array, the option can takes multiple option arguments, therefore it can appear multiple times in command line arguments.

      A Opt field annotation can have the following pairs of name and value: one is cfg to specify names and defaults fields of OptCfg struct, another is desc to specify desc field, and yet another is arg to specify argInHelp field.

      The format of cfg is like cfg="f,foo=123". the left side of the equal sign is the option name(s), and the right side is the default value(s). If there is no equal sign, it is determined that only the option name is specified. If you want to specify multiple option names, separate them with commas. If you want to specify multiple default values, separate them with commas and round them with square brackets, like [1,2,3]. If you want to use your favorite character as a separator, you can use it by putting it on the left side of the open square bracket, like /[1/2/3].

      NOTE: A default value of empty string array option in a field attribute is [], like @Opt(cfg="=[]"), but it doesn't represent an array which contains only one empty string. If you want to specify an array which contains only one empty string, write nothing after = symbol, like Opt(cfg="=").

      Parameters:
      optStore - An object store.
      Throws:
      InvalidOption - If failed to parsing command line arguments.
      FailToSetOptionStoreField - If failed to set a field value of an object store.

    • parseUntilSubCmdFor

      public Optional<Cmd> parseUntilSubCmdFor(Object optStore) throws InvalidOption, FailToSetOptionStoreField
      Parses command line arguments until the first command argument and set their option values to the option store which is passed as an argument. This method creates and returns a new Cmd instance that holds the command line arguments starting from the first command argument. This method parses command line arguments in the same way as the parseFor(java.lang.Object) method, except that it only parses the command line argments before the first command argument.
      Parameters:
      optStore - An object store.
      Returns:
      A Cmd instance which holds commnd line arguments after a sub command (optional).
      Throws:
      InvalidOption - If failed to parsing command line arguments.
      FailToSetOptionStoreField - If failed to set a field value of an object store.