<?xml version="1.0"?>

<!--
	description:

		"Options"

	copyright: "Copyright (c) 2006, Bernd Schoeller and others"
	license: "MIT License"
	date: "$Date: 2007-09-20 07:54:24 -0700 (Thu, 20 Sep 2007) $"
	revision: "$Revision: 6088 $"
-->

<chapter xmlns="http://www.gobosoft.com/eiffel/gobo/documentation" id="argument/error">
<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>Options</title>

<para>
	<classname>AP_OPTION</classname> is the common superclass of
	all options. It defines the fact that options can have a short
	and a long form and a descriptive text. It also can count the
	occurrences of an option and can mark the option as
	mandatory.
</para>

<para>
	<classname>AP_OPTION_WITH_PARAMETER[G]</classname> extends
	<classname>AP_OPTION</classname> with the possibility of
	recoding parameters of type <classname>G</classname>. All
	options except for <classname>AP_FLAG</classname> inherit from
	this class.
</para>

<section id="available">
	
	<title>Available option types</title>

	<para>
		The following standard option types are available:
	</para>

	<variablelist>
		<varlistentry>
			<term>
				<classname>AP_FLAG</classname>
			</term>
			<listitem><para>
				A simple flag that does not take an
				argument.
			</para></listitem>
		</varlistentry>
		<varlistentry>
			<term>
				<classname>AP_STRING_OPTION</classname>
			</term>
			<listitem><para>
				A flag that takes an arbitrary string
				as argument.
			</para></listitem>
		</varlistentry>
		<varlistentry>
			<term>
				<classname>AP_BOOLEAN_OPTION</classname>
			</term>
			<listitem><para>
				
				The flag needs to be supplied by a
				boolean value. The strings
				'yes','y','1','true' and 't' are
				regarded as true. The strings
				'no','n','0','false' and 'f' are
				regarded as false.

			</para></listitem>
		</varlistentry>
		<varlistentry>
			<term>
				<classname>AP_ENUMERATION_OPTION</classname>
			</term>
			<listitem><para>

				The enumeration options allows to
				choose one string out of a fixed set
				of choices. Available choices can be
				added to the option through the
				<featurename>extend</featurename>
				call.

			</para></listitem>
		</varlistentry>
		<varlistentry>
			<term>
				<classname>AP_INTEGER_OPTION</classname>
			</term>
			<listitem><para>

				This option takes an integer as an
				argument. Parsing will yield an error
				if no integer value is passed.

			</para></listitem>
		</varlistentry>
		<varlistentry>
			<term>
				<classname>AP_DISPLAY_HELP_FLAG</classname>
			</term>
			<listitem><para>

				This is a special flag to display a
				help message. It is normally added
				automatically through the call of
				<featurename>make</featurename> in
				<classname>AP_PARSER</classname>.

			</para></listitem>
		</varlistentry>
	</variablelist>

</section>

<section id="ownoptions">
	
	<title>Defining own option types</title>

	<para>
		It should be easy to implement own option types do
		define own parameters, for example for file names or
		dates. It is best to inherit form
		<classname>AP_OPTION_WITH_PARAMETER</classname> or one
		of its decedents.
	</para>

</section>

<section id="optional_parameters">

	<title>Options with optional parameters</title>

	<para>
		Sometimes, mostly for backward compatibility, it is
		necessary to make the parameter to an option
		optional. This can be done by calling the
		<featurename>set_parameter_as_optional</featurename>
		feature in class
		<classname>AP_STRING_OPTION</classname>. To prevent
		the grammar from becoming ambiguous, this only works
		for long options. Also, it is impossible to use the
		space as a delimiter between option and parameter:
		'--foo=X' will parse as option foo with parameter 'X',
		'--foo X' will parse as foo without a parameter, and
		then the global parameter 'X'.
	</para>

	<para>
		The parameters list in the option will record usages
		of the option without parameters as Void values.
	</para>

</section>

</chapter>
