2001-2006
Bernd Schoeller
Bernd
Schoeller
bernd@fams.de 14 September 2006

# Alternative Options Lists

Some application offer different 'modes' of operation, each one with a different set of options. For example, a compression program (think WinZip or gzip) may be used for compression and for decompression of files. In decompression mode, specifying the compression algorithm to use does not make any sense, as the program should be able to extract this information directly from the compressed file.

Alternative options lists allows you to define sets of options for different operation modes of the application. The very first option passed to the application is used to select one of the operation modes, altering the set of available options.

## Usage

Alternative options lists are created by instantiating `ALTERNATIVE_OPTIONS_LIST` and adding it to the alternative_options_lists list in `AP_PARSER` in the same way as options are added to the options list.

`ALTERNATIVE_OPTIONS_LIST` is itself a list (a child of `DS_LINKED_LIST[AP_OPTION]`) that can contain option objects. Upon creation, a special option needs to be provided to make, the introduction option. If the first option that is encountered during parsing is the introduction option, then the list of available options during parsing will be replaced by the list provided in the alternative option list.

The same option can be added to the default options list in `AP_PARSER` as well as to an arbitrary set of `ALTERNATIVE_OPTIONS_LIST` at the same time. This makes it possible to offer the same option in different modes.

## Example

The following example creates a compression program that allows the user to compress and decompress files. The default is compression, while decompression can be introduced with --decompress (or -d). Compression allows the selection of a compression strength (1..9), decompression can add a checksum check. Both allow the specification of an output file.

    class COMPR

    create

       make

    feature -- Options and Flags

       decompress_flag: AP_FLAG
       strength_option: AP_INTEGER_OPTION
       check_flag: AP_FLAG
       output_option: AP_STRING_OPTION

    feature -- Main

       make is
             -- Main routine, called when the program is executed.
          local
             parser: AP_PARSER
             alternative_list: AP_ALTERNATIVE_OPTIONS_LIST
          do
             create parser.make
             parser.set_application_description ("Compress or decompress a file")
             parser.set_parameters_description ("file")

             create decompress_flag.make ('d',"decompress")
             decompress_flag.set_description ("Decompress file")

             create strength_option.make ('s',"strength")
             strength_option.set_description ("Compression strength (1..9)")

             create check_flag.make ('c',"check")
             check_flag.set_description ("Enable checksum computation after decompression")

             create output_option.make ('o',"output")
             output_option.set_description ("Output to specified file")
             output_option.set_parameter_description ("file")

             parser.options.force_last (strength_option)
             parser.options.force_last (output_option)

             create alternative_list.make (decompress_flag)
             alternative_list.force_last (check_flag)
             alternative_list.force_last (output_option)
             alternative_list.set_parameters_description ("compressed_file")
             parser.alternative_options_lists.force_first (alternative_list)

             parser.parse_arguments
          end

    end

The generated help text looks like this:

    $ ./compr -h
    usage: compr [-s int] [-o file] file
           compr --decompress [-c] [-o file] compressed_file
           compr --help

    Compress or decompress a file

    Options:
    -c, --check        Enable checksum computation after decompression
    -d, --decompress   Decompress file
    -h, --help         Display this help text.
    -o, --output=file  Output to specified file
    -s, --strength=int Compression strength (1..9)

Command line parsing will reject the -c flag without a -d flag, also it will reject the -s option when the -d flag is provided. The -o option is always accepted.

P.S.: You can see that the help flag was also added using an empty alternative options list.