Usage

List of alternative options 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 (an heir 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 list of alternative options.

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
         -- 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.

Note that the help flag was also added using an empty list of alternative options.