<?xml version="1.0"?>

<!--
	description:

		"Alternative Options Lists"

	copyright: "Copyright (c) 2006, Bernd Schoeller and others"
	license: "MIT License"
	date: "$Date: 2007-01-26 10:55:25 -0800 (Fri, 26 Jan 2007) $"
	revision: "$Revision: 5877 $"
-->

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

<title>Alternative Options Lists</title>

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

<para>
	<emphasis>Alternative options lists</emphasis> 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.
</para>

<section id="usage">
	
	<title>Usage</title>

	<para>
		Alternative options lists 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 (a child 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 alternative option list.

	</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 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
</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>
		<emphasis>P.S.:</emphasis> You can see that the help
		flag was also added using an empty alternative options
		list.
	</para>

</section>

</chapter>
