<?xml version="1.0"?>

<!--
	description:

		"Lists of Alternative Options"

	copyright: "Copyright (c) 2006-2019, Bernd Schoeller and others"
	license: "MIT License"
-->

<chapter xmlns="https://www.gobosoft.com/eiffel/gobo/documentation" id="argument/alternate">
<chapterinfo>
	<copyright>
		<year>2001-2019</year>
		<holder>Bernd Schoeller</holder>
	</copyright>
	<author>
		<firstname>Bernd</firstname><surname>Schoeller</surname>
	</author>
	<email>bernd@fams.de</email>
	<date>27 February 2019</date>
</chapterinfo>

<title>Lists of Alternative Options</title>

<para>
	Some applications offer different 'modes' of operation, each
	one with a different set of options. For example, a
	compression program (think of 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.
</para>

<para>
	<emphasis>Lists of alternative options</emphasis> allow 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.
</para>

<section id="usage">

	<title>Usage</title>

	<para>
		List of alternative options are created by instantiating
		<classname>ALTERNATIVE_OPTIONS_LIST</classname> and
		adding it to the
		<featurename>alternative_options_lists</featurename>
		list in <classname>AP_PARSER</classname> in the same
		way as options are added to the
		<featurename>options</featurename> list.
	</para>

	<para>

		<classname>ALTERNATIVE_OPTIONS_LIST</classname> is
		itself a list (an heir of
		<classname>DS_LINKED_LIST [AP_OPTION]</classname>) that
		can contain option objects. Upon creation, a special
		option needs to be provided to
		<featurename>make</featurename>, the
		<emphasis>introduction option</emphasis>. 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.

	</para>

	<para>

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

	</para>

</section>

<section id="example">

	<title>Example</title>

	<para>

		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.

	</para>

<programlisting>
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
</programlisting>

	<para>
		The generated help text looks like this:
	</para>

<programlisting>
$ ./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)
</programlisting>

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

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

</section>

</chapter>
