Package io.ciera.runtime.summit.util

Interface CMD

  • All Known Implementing Classes:
    CMDImpl
    public interface CMD

    Provides a mechanism for defining command line interfaces and reading values and flags from the command line arguments.

    The CMD external entity is used in two phases: defining and reading. First, the interface is defined using the register_flag and register_value bridges. Once the interface is defined, the read_command_line bridge must be invoked to finalize the usage and parse the command line arguments. After the command line arguments are parsed, the get_flag and get_value bridges can be used to access the values passed by the user on the command line.

    The utility expects that all invocations of the "register" bridges are before the read_command_line bridge is invoked, that the read_command_line bridge is invoked at most once, and that all invocations of the "get" bridges are after the read_command_line bridge is invoked. Violation of this order will result in an exception.

    Flags and values can be defined by one or more alphanumeric characters, underscores, and hyphens (starting with an alphabetic character). Single character flags/values are specified on the command line with a single hyphen (e.g. -i), while multi-character flags/values must be specified with two hypens (e.g. --input_file). The flags -h and --help are reserved and are always included in order to print usage text.

    A flag is considered to be true if the flag appears anywhere on the command line. A value is defined as the argument that directly follows the registered option name (e.g. --input_file in.sql). Values may not be repeated on the command line and are always returned to the caller as a string. Numerical or other types of values must be converted after the fact by the application modeler.

    • Method Detail

      • get_flag

        boolean get_flag​(String name)
          throws XtumlException
        Get the value of a registered command line flag.
        Parameters:
        name - the name of the flag
        Returns:
        true if the flag was passed as a command line argument, false if otherwise
        Throws:
        XtumlException - if the command line has not been read, the flag name has not been registered, or if the flag has been registered as a value.

      • get_value

        String get_value​(String name)
          throws XtumlException
        Get the value of a registered command line value.
        Parameters:
        name - the name of the value
        Returns:
        the value of the option passed on the command line or the registered default value if not present and not required
        Throws:
        XtumlException - if the command line has not been read, the value name has not been registered, or if the value has been registered as a flag.

      • read_command_line

        void read_command_line()
                throws XtumlException,
                       XtumlInterruptedException
        Parse and validate the command line arguments based on the previously registered flags and values. If an excption is thrown, the usage is printed to the command line and the application will exit.
        Throws:
        XtumlException - if the command line has already been read
        XtumlInterruptedException - if the command line arguments are incorrectly formatted or if an option that requires a value does not provide a value.

      • register_flag

        void register_flag​(String name,
                   String usage)
            throws XtumlException
        Register a command line flag.
        Parameters:
        name - the name of the flag
        usage - the help text to display in the usage
        Throws:
        XtumlException - if the command line has already been read, the flag name has already been registered, or if the flag name is invalid.

      • register_value

        void register_value​(String name,
                    String value_name,
                    String usage,
                    String default_value,
                    boolean required)
             throws XtumlException
        Register a command line value. If the flag is required, the default_value parameter is ignored.
        Parameters:
        name - the name of the value
        value_name - the placeholder name of the value to display in the usage
        usage - the help text to display in the usage
        default_value - the default value of the option if not required and no value is specified
        required - whether or not a value is required
        Throws:
        XtumlException - if the command line has already been read, the option name has already been registered, or if the option name is invalid.