SimpleOption v1.0 

 The Simple Development Library command line options parser 

Project: the Simple Development Library.

Table of contents

1. Package description

Synopsis: the Simple Development Library command line options parser.

Keywords: option, flag, parameter and command line.

1.1 Overview

This package provides a powerful command line options parser. Features include:

• Each option has a primary flag and an optional secondary flag, so that any of them can be used in the command line.

• The special option "--" is used to collect the arguments at the end of the command line not belonging to other options. In the command line, "--" can be used to inhibit the processing of the arguments following it.

• Each option can optionally have a name. The name is used in the options usage string and other references to the option.

• Each option has a type to which the option values must conform. Types are implemented via the SimpleType package, so a wealth of predefined types are available and further types can be defined.

• Options with numeric types can optionally have a numeric range to which the option values must conform.

• Options with type "choice" or derived from it have a list of allowed choices to which the option values must conform.

• Each option can optionally have a default value.

• Each option can optionally have a range of values to which the option number of values must conform. By default, each option admits a single value.

• Options can be optional or compulsory (not really options then, as Harald Kirsh, clig's author, first noted).

• The presence or absence of certain options can be made optional, compulsory or disallowed depending on the presence or absence of other options. For two options, the possibilites are:

• -a -b: both -a and -b are compulsory

• -a [-b]: -a is compulsory and -b is optional

• [-a -b]: both -a and -b are optional, but if one is given the other must be also given.

• [-a [-b]]: both -a and -b are optional, but -b can not be given unless -a is also present.

• (-a | -b): one of -a or -b must be given.

• [(-a | -b)]: both -a and -b are optional, but both can not be simultaneously given.

Other relations are possible (and are accepted) but are equivalente to one of the ones above. For example, the last relation [(-a | -b)] can also be expressed as either (-a | [-b]) or ([-a] | -b).

These basic usage relations between two options can be combined to yield almost any imaginable usage relations between three or more options and beyond.

• The package automatically builds the options usage string.

Procedures are provided to declare options, declare their usage relations, reset the declared options and their usage relations, parse a command line with respect to the declared options and usage relations and get the options usage string. After a command line has been parsed, procedures are provided to assess whether a certain option was given in the command line, to assess whether it is available (that is, whether it has a default value or has been given in the command line), to get the value of an available option and to assess whether the value of an available option is that option default value.

1.2 Usage

Options are declared via the ::Simple::Option::declare procedure. The declaration of each option includes its flag or flags, its name, its type, its description, its number of values and its values numeric range, choices and default value.

The declared options usage relations is specified via the ::Simple::Option::declare-usage procedure. Use ::Simple::Option::reset to reset the declared options and usage information.

The ::Simple::Option::information procedure provides several subcommands to query information about the options and the actual command line: available, choices, declared, default, defaultgiven, description, given, help, isdefault, name, range, secondary, type, usage, value and values.

1.3 Examples

# Install the package
package require SimpleDevLibPackage 1.0
::Simple::Package::require-and-install SimpleOption

# Declare the program options
::Simple::Option::declare {-p --processing} -type choice\ 
   -choices {A B C} -description {processing option}
::Simple::Option::declare {-v --verbosity} -name verbosity -type integer\ 
   -range -1:4 -description {set the verbosity level}
::Simple::Option::declare {-w --width} -name width -type integer\ 
   -default 80 -description {set the width of the output}
::Simple::Option::declare {-a --all} -type boolflag\ 
   -description {process all files}

# The special option "--" is used to collect the arguments at the
# end of the command line not belonging to other options
::Simple::Option::declare -- -name files -type string\ 
   -values 3: -description {files to process}

# Declare the options usage:  -p is compulsory, -v and -w are
# optional, one of -a or a list of files must be given.
::Simple::Option::declare-usage {-p {O -v} {O -w} {X -a --}}

# Display the options usage string
# This displays the following:
#   |-p choice [-v verbosity] [-w width] (-a | files(3:))
puts [::Simple::Option::information usage]

# Display the help message
# This displays the following:
#   |-p, --processing           processing option (A, B or C)
#   |-v, --verbosity VERBOSITY  set the verbosity level
#   |-w, --width WIDTH          set the width of the output (default 80)
#   |-a, --all                  process all files
#   |files                      files to process
foreach optionPair [::Simple::Option::information help] {
   foreach {reference description} $optionPair break
   puts [format {%-26s %s} $reference $description]
}

# Now parse some possible command lines

# This displays the following:
#   |"-p" (or "--processing") required
catch {::Simple::Option::parse {-w 132 -a}} result
puts $result

# This displays the following:
#   |invalid value "D" for option "-p" of type "choice": must be A, B or C
catch {::Simple::Option::parse {-p D -a}} result
puts $result

# This displays the following:
#   |invalid value "foo" for option "-w" of type "integer"
catch {::Simple::Option::parse {-p A -w foo -a}} result
puts $result

# This displays the following:
#   |one of "-a" (or "--all") or "files" required
catch {::Simple::Option::parse {-p A}} result
puts $result

# This displays the following:
#   |too few values, 3: files required, got 2
catch {::Simple::Option::parse {-p A file1 file2}} result
puts $result

# This displays the following:
#   |invalid value "7" for option "-v": value out of range "-1:4"
catch {::Simple::Option::parse {-p A -v 7 -a}} result
puts $result

# A valid command line
::Simple::Option::parse {-p A -v 3 -a}

# Assess the available options values
# This displays the following:
#   |The value of option -p is A
#   |The value of option -v is 3
#   |The value of option -w is 80
#   |The value of option -a is 1
#   |Option -- not available
foreach option [::Simple::Option::information declared] {
   if {[::Simple::Option::information available $option]} {
      puts "The value of option $option is [::Simple::Option::information value $option]"
   } else {
      puts "Option $option not available"
   }
}

1.4 History

1.5 Copyright

Copyright (C) 1999-2005, Juan C. Gil (jgil@gmv.es).

2. Package public API

Paradigm: procedural.

Requisites: SimpleDeclare 1.0.

2.1 Types

None.

2.2 Options

None.

2.3 Namespaces

1. ::Simple::Option

2. ::Simple::Option::Priv

2.4 Commands

2.4.1 ::Simple::Option::cget

Synopsis: gets the package options.

Details: see section 4.1.

2.4.2 ::Simple::Option::configure

Synopsis: configures the package options.

Details: see section 4.2.

2.4.3 ::Simple::Option::declare optionPair ?-name word? ?-type type? ?-range number-range? ?-choices any-list? ?-default any? ?-values decimal-range? ?-description string?

Synopsis: declares an option.

Details: see section 4.3.

2.4.4 ::Simple::Option::declare-usage usageGroups

Synopsis: specifies the options usage.

Details: see section 4.4.

2.4.5 ::Simple::Option::information available option

Synopsis: returns whether an option is available.

Details: see section 4.5.

2.4.6 ::Simple::Option::information choices option

Synopsis: returns an option choices.

Details: see section 4.6.

2.4.7 ::Simple::Option::information declared

Synopsis: returns the list of declared options.

Details: see section 4.7.

2.4.8 ::Simple::Option::information default option

Synopsis: returns an option default value.

Details: see section 4.8.

2.4.9 ::Simple::Option::information defaultgiven option

Synopsis: returns whether an option has a default value.

Details: see section 4.9.

2.4.10 ::Simple::Option::information description option

Synopsis: returns an option description.

Details: see section 4.10.

2.4.11 ::Simple::Option::information given option

Synopsis: returns whether an option was given in the command line.

Details: see section 4.11.

2.4.12 ::Simple::Option::information help

Synopsis: returns the option flag(s) and description pairs.

Details: see section 4.12.

2.4.13 ::Simple::Option::information isdefault option

Synopsis: returns whether the value of an option is the default one.

Details: see section 4.13.

2.4.14 ::Simple::Option::information name option

Synopsis: returns an option name.

Details: see section 4.14.

2.4.15 ::Simple::Option::information range option

Synopsis: returns an option range.

Details: see section 4.15.

2.4.16 ::Simple::Option::information secondary option

Synopsis: returns an option secondary flag.

Details: see section 4.16.

2.4.17 ::Simple::Option::information type option

Synopsis: returns an option type.

Details: see section 4.17.

2.4.18 ::Simple::Option::information usage

Synopsis: returns the options usage string.

Details: see section 4.18.

2.4.19 ::Simple::Option::information value option

Synopsis: returns an option value.

Details: see section 4.19.

2.4.20 ::Simple::Option::information values option

Synopsis: returns an option number of values.

Details: see section 4.20.

2.4.21 ::Simple::Option::parse commandLine

Synopsis: parses a command line.

Details: see section 4.21.

2.4.22 ::Simple::Option::reset

Synopsis: resets the declared options and usage information.

Details: see section 4.22.

2.5 Errors

2.5.1 ::Simple::Option::DOUBLE-HYPHEN-NOT-AS-SECONDARY

Message: "--" can not be a secondary option flag.

Explanation: an option declaration failed because "--" was supplied as a secondary option flag, but that is not allowed.

2.5.2 ::Simple::Option::DOUBLE-HYPHEN-NOT-SECONDARY

Message: "--" can not have a secondary option flag.

Explanation: the declaration of option "--" failed because it was accompanied with a secondary option flag, but that is not allowed.

2.5.3 ::Simple::Option::DOUBLE-HYPHEN-REQUIRES-NAME

Message: option "--" requires a name.

Explanation: the declaration of option "--" failed because it lacks the customary option name.

2.5.4 ::Simple::Option::DOUBLE-HYPHEN-NOT-ALLOWED

Message: "--" not allowed.

Explanation: "--" in the command line is not allowed because it was not declared, that is, only arguments associated to options are allowed.

2.5.5 ::Simple::Option::ALREADY-DECLARED

Message: option "flag" already declared.

Explanation: option flag has already been declared.

2.5.6 ::Simple::Option::ALREADY-DECLARED-AS-SECONDARY

Message: option "secondary flag" already declared as secondary of "primary flag".

Explanation: option secondary flag has already been declared as the secondary flag of primary flag.

2.5.7 ::Simple::Option::NON-EXISTING-TYPE

Message: non-existing type "type" for option "flag".

Explanation: the declaration of option flag failed because the type type does not exists.

2.5.8 ::Simple::Option::NO-RANGE-ALLOWED

Message: no range allowed for option "flag" of type "type".

Explanation: the declaration of option flag failed because a range was supplied, but the type type does not allow ranges.

2.5.9 ::Simple::Option::BAD-RANGE

Message: invalid range "range" for option "flag" of type "type".

Explanation: the declaration of option flag failed because range is not a valid range for type type.

2.5.10 ::Simple::Option::VALUE-OUT-OF-RANGE

Message: invalid[ default] value "value" for (option flag|option name): value out of range "range".

Explanation: the declaration of option flag failed, or its command line value is incorrect, because the value value is out of the range range.

Corrective action: either supply a value within the range or modify the range.

2.5.11 ::Simple::Option::NO-VALUES-ALLOWED

Message: no values allowed for option "flag" of type "boolflag".

Explanation: the declaration of option flag failed because the type boolflag does not allow specifying a value.

2.5.12 ::Simple::Option::USAGE-NOT-SPECIFIED

Message: usage for option "flag" not specified.

Explanation: option flag was not specified in the declaration of the options usage via ::Simple::Option::declare-usage.

Corrective action: give all declared options when calling ::Simple::Option::declare-usage.

2.5.13 ::Simple::Option::NO-NON-OPTIONAL-OPTION-IN-OPTIONAL-GROUP

Message: no non-optional option within optional group "bad optional group".

Explanation: a call to ::Simple::Option::declare-usage includes a bad optional group. Optional groups must include at least one non-optional option, that is, not within another nested optional group.

2.5.14 ::Simple::Option::NOT-ENOUGH-ALTERNATIVES-IN-EXCLUSIVE-GROUP

Message: not enough alternatives in exclusive group "bad exclusive group".

Explanation: a call to ::Simple::Option::declare-usage includes a bad exclusive group. An exclusive group is made of an "X" specifier followed by two or more major option groups.

2.5.15 ::Simple::Option::BAD-MAJOR-GROUP

Message: bad major group "bad major group".

Explanation: a call to ::Simple::Option::declare-usage includes a bad major group. A major group is either a single option, a group, an exclusive group or an optional group.

2.5.16 ::Simple::Option::EXCLUSIVE-GROUP-AS-ALTERNATIVE

Message: exclusive group "exclusive group" is an alternative for previous exclusive group.

Explanation: a call to ::Simple::Option::declare-usage includes an exclusive group which is by itself an alternative for a previous exclusive group. For example, the call ::Simple::Option::declare-usage {{X -a {X -b -c}}} would give rise to this error as the exclusive group {X -b -c} is an alternative for the exclusive group {X -a ...}.

2.5.17 ::Simple::Option::UNDECLARED-OPTION

Message: unrecognized option "flag".

Explanation: option flag has not been declared.

Corrective action: either use ::Simple::Option::declare to declare the option flag or get rid of the offending option.

2.5.18 ::Simple::Option::NOT-A-PRIMARY-OPTION

Message: not a primary option flag "flag".

Explanation: option flag flag is not a primary option flag, but the invoked procedure requires the use of primary flags.

2.5.19 ::Simple::Option::OPTIONS-EXCLUDE-EACH-OTHER

Message: options "flag 1" and "flag 2" exclude each other.

Explanation: options flag 1 and flag 2 exclude each other, but both have been given simultaneously.

Corrective action: provide one of the two flags only.

2.5.20 ::Simple::Option::OPTION-REQUIRED

Message: required flag required.

Explanation: option required flag is required, but it has not been given.

2.5.21 ::Simple::Option::OPTION-GIVEN-REQUIRED

Message: given flag given, required flag required.

Explanation: option given flag was given, option that requires option required flag, but the later has not been given.

2.5.22 ::Simple::Option::ONE-OF-OPTIONS-REQUIRED

Message: one of flags list required.

Explanation: one of the options in the flags list is required.

2.5.23 ::Simple::Option::OPTION-GIVEN-ONE-OF-REQUIRED

Message: given flag given, one of required flags list required.

Explanation: option given flag was given, but one of the options in the required flags list is required by the given one.

2.5.24 ::Simple::Option::EXTRA-VALUES

Message: extra value(s) "values".

Explanation: the values values in the command line can not be used.

2.5.25 ::Simple::Option::TOO-MANY-OR-FEW-VALUES-1

Message: too may or few values for option "option", range required, got actual number of values.

Explanation: too may or few values have been given for option option. The required range is range, but the number of given values is actual number of values.

2.5.26 ::Simple::Option::TOO-MANY-OR-FEW-VALUES-2

Message: too many or few values, range option name required, got actual number of values.

Explanation: too may or few option name, the required range is range, but the number of given values is actual number of values.

2.5.27 ::Simple::Option::VALUE-NOT-AVAILABLE

Message: value not available for option "flag".

Explanation: the option flag value has been requested, but it is not available.

Corrective action: use ::Simple::Option::information available to assess whether an option value is available or not.

3. Package further information

3.1 Details

The following is a side-by-side comparison between the functionality provided by this package for command line options and that for procedure arguments provided by the SimpleProc package:

Run-time type checking

SimpleProc: no implicit arguments run-time type checking by default (this can be changed by setting the -checktype SimpleProc or using the -checktype flag for proc-ext or declare-proc).

SimpleOption: implicit options run-time type checking.

Flag or option given

SimpleProc: ::Simple::Argument::information flaggiven returns whether a flag argument has been given in the procedure call.

SimpleOption: ::Simple::Option::information given returns whether an option was given in the command line.

Values availability

SimpleProc: all arguments are available as both flags and optional arguments require a default value upon declaration.

SimpleOption: not all options are available, only those for which a default value has been defined, boolean flags and options in the actual command line. Use ::Simple::Option::information available to assess whether an option is available.

Values retrieval

SimpleProc: all argument values go to variables.

SimpleOption: no option value goes to any variable, it must be fetched with ::Simple::Option::information value.

Usage string

SimpleProc: the procedure argument usage string is got via ::Simple::Proc::information usage.

SimpleOption: the options usage is got via ::Simple::Option::information usage.

List of values

SimpleProc: ::Simple::Proc::information args returns a procedure argument names list.

SimpleOption: ::Simple::Option::information declared returns the list of declared options.

Value equal to the default

SimpleProc: ::Simple::Argument::information isdefault returns whether an argument value is equal to its default.

SimpleOption: ::Simple::Option::information isdefault returns whether an option value is equal to its default.

3.2 References

• The command line interpreter generator (clig) at http://wsd.iitb.fhg.de/~kir/clighome.

3.3 Todo

• Add ::Simple::Option::information requires and ::Simple::Option::information excludes which returns the list of options a given option requires or excludes, respectively.

• Allow more than one set of options, identifying them by name.

4. Package command details

4.1 ::Simple::Option::cget

4.1.1 Command description

Synopsis: gets the package options.

Access mode: public.

4.1.2 Command public API

Arguments: none.

Returns: the requested option value or the whole list of options if none specified.

4.2 ::Simple::Option::configure

4.2.1 Command description

Synopsis: configures the package options.

Access mode: public.

4.2.2 Command public API

Arguments: none.

Returns: the "package with no options" error is thrown.

4.3 ::Simple::Option::declare optionPair ?-name word? ?-type type? ?-range number-range? ?-choices any-list? ?-default any? ?-values decimal-range? ?-description string?

4.3.1 Command description

Synopsis: declares an option.

Access mode: public.

4.3.1.1 Overview

This procedure is used to declare a new option.

Each option has a primary flag and an optional secondary flag, so that any of them can be used in the command line. The special option "--" is used to collect the arguments at the end of the command line not belonging to other options. In the command line, "--" can be used to inhibit the processing of the arguments following it.

Use -name to set the option name. The option name is used in the options usage string and other references to the option.

If -type is given, the option type is set to the given type, otherwise the option type is set to any.

If -range is given, the option values must be in the given range.

When the option type is choice or derived from it, -choices is required. This specifies the list of allowed choices to which the option values must conform.

Use -default to specify a default value for the option.

If -values is given, the number of allowed values for the option is limited by the given range.

4.3.2 Command public API

Arguments:

Returns: the empty string.

4.4 ::Simple::Option::declare-usage usageGroups

4.4.1 Command description

Synopsis: specifies the options usage.

Access mode: public.

4.4.1.1 Overview

By default, all options are optional and independent. This procedure allows to alter that behaviour by specifying relationships between options via usage option groups.

Each usage option group contains options whose presence or absence in the command line is optional, compulsory or disallowed depending on the presence or absence of other options from the same usage option group in the command line. Options in different usage option groups are, thus, fully independent. These relationships are specified via an special-purpose syntax which is described below.

Each usage option group is either a single option primary flag, an optional group or an exclusive group:

• An optional group is made of an "O" specifier followed by one or more elements among single options, optional groups or exclusive groups. At least one element within an optional group (either directly or within other contained groups) must be a required option.

Options in an optional group are optional in the command line.

• An exclusive group is made of an "X" specifier followed by two or more exclusive major groups. Exclusive major groups are made of one or more elements among single options, optional groups or exclusive groups. At least one exclusive major group must not be an exclusive group.

Options in different exclusive major groups of an exclusive group are mutually exclusive in the command line.

These rules are summarised in the following pseudo-BNF syntax:

UsageGroup := (SingleOption | OptionalGroup | ExclusiveGroup) OptionalGroup := O NoOptionalUsageGroup [UsageGroup ...] NoOptionalUsageGroup := (SingleOption | ExclusiveGroup) NoExclusiveUsageGroup := (SingleOption | OptionalGroup) ExclusiveGroup := X ExclusiveMajorGroup ExclusiveMajorGroup [ExclusiveMajorGroup ...] ExclusiveMajorGroup := NoExclusiveUsageGroup [UsageGroup ...]

If this procedure is invoked, the usage of all declared options must be specified.

4.4.2 Command public API

Arguments:

Returns: the empty string.

4.5 ::Simple::Option::information available option

4.5.1 Command description

Synopsis: returns whether an option is available.

Access mode: public.

4.5.1.1 Overview

This procedure returns whether an option is available or not. The option flag must be primary.

4.5.2 Command public API

Arguments:

Returns: whether the option is available.

4.6 ::Simple::Option::information choices option

4.6.1 Command description

Synopsis: returns an option choices.

Access mode: public.

4.6.1.1 Overview

This procedure returns an option choices. The option flag must be primary.

4.6.2 Command public API

Arguments:

Returns: the option choices.

4.7 ::Simple::Option::information declared

4.7.1 Command description

Synopsis: returns the list of declared options.

Access mode: public.

4.7.1.1 Overview

This procedure returns the list of primary declared option flags.

4.7.2 Command public API

Arguments: none.

Returns: the list of primary declared option flags.

4.8 ::Simple::Option::information default option

4.8.1 Command description

Synopsis: returns an option default value.

Access mode: public.

4.8.1.1 Overview

This procedure returns an option default value. The option flag must be primary.

4.8.2 Command public API

Arguments:

Returns: the option default value.

4.8.3 Command further information

4.8.3.1 References

• The ::Simple::Variable::information default procedure.

• The ::Simple::ItkOption::information default procedure.

4.9 ::Simple::Option::information defaultgiven option

4.9.1 Command description

Synopsis: returns whether an option has a default value.

Access mode: public.

4.9.2 Command public API

Arguments:

Returns: whether the option has default value.

4.9.3 Command further information

4.9.3.1 References

• The ::Simple::Variable::information defaultgiven procedure.

• The ::Simple::ItkOption::information defaultgiven procedure.

4.10 ::Simple::Option::information description option

4.10.1 Command description

Synopsis: returns an option description.

Access mode: public.

4.10.1.1 Overview

This procedure returns an option description. The option flag must be primary.

4.10.2 Command public API

Arguments:

Returns: the option description.

4.11 ::Simple::Option::information given option

4.11.1 Command description

Synopsis: returns whether an option was given in the command line.

Access mode: public.

4.11.1.1 Overview

This procedure returns whether an option was given in the last call to ::Simple::Option::parse. The option flag must be primary.

4.11.2 Command public API

Arguments:

Returns: whether the option was given in the command line.

4.11.3 Command further information

4.11.3.1 References

• The ::Simple::Priv::flag-given procedure.

• The ::Simple::Argument::information flaggiven procedure.

4.12 ::Simple::Option::information help

4.12.1 Command description

Synopsis: returns the option flag(s) and description pairs.

Access mode: public.

4.12.1.1 Overview

This procedure returns a list of pairs. Each element in the list corresponds to an option.

The first element of each pair is the option reference, including the primary and secondary option flags (if any) plus the option name or type, when applicable.

The second element of each pair is the option description, including the string given as argument to the -description flag of ::Simple::Option::declare plus the list of options and default value, when applicable.

The return value of this procedure can be used to provide a help message; this is used by the declare-program procedure of the SimpleProgram package.

4.12.2 Command public API

Arguments: none.

Returns: the option flag(s) and description pairs.

4.13 ::Simple::Option::information isdefault option

4.13.1 Command description

Synopsis: returns whether the value of an option is the default one.

Access mode: public.

4.13.1.1 Overview

This procedure returns whether an option is available and its actual value matches its default value. For unavailable options, this procedure returns always false. The option flag must be primary.

4.13.2 Command public API

Arguments:

Returns: whether the option is available and its actual value matches its default value.

4.13.3 Command further information

4.13.3.1 References

• The ::Simple::Argument::information isdefault procedure.

4.14 ::Simple::Option::information name option

4.14.1 Command description

Synopsis: returns an option name.

Access mode: public.

4.14.1.1 Overview

This procedure returns an option name. The option flag must be primary.

4.14.2 Command public API

Arguments:

Returns: the option name.

4.15 ::Simple::Option::information range option

4.15.1 Command description

Synopsis: returns an option range.

Access mode: public.

4.15.1.1 Overview

This procedure returns an option range. The option flag must be primary.

4.15.2 Command public API

Arguments:

Returns: the option range.

4.16 ::Simple::Option::information secondary option

4.16.1 Command description

Synopsis: returns an option secondary flag.

Access mode: public.

4.16.1.1 Overview

This procedure returns an option secondary flag. The option flag must be primary.

4.16.2 Command public API

Arguments:

Returns: the option secondary flag.

4.17 ::Simple::Option::information type option

4.17.1 Command description

Synopsis: returns an option type.

Access mode: public.

4.17.1.1 Overview

This procedure returns an option type. The option flag must be primary.

4.17.2 Command public API

Arguments:

Returns: the option type.

4.18 ::Simple::Option::information usage

4.18.1 Command description

Synopsis: returns the options usage string.

Access mode: public.

4.18.1.1 Overview

This procedure returns the options usage string as declared by the ::Simple::Option::declare-usage procedure, or the default usage string (all options are optional) if that procedure has not been used.

Each declared option appears in the options usage string with its description, which is either the option name (if available) or the option type. If the option range is non-trivial (that is, different from "1") that is also added, between parenthesis.

Optional option groups appear between square brackets, such as in [-a -b]. Exclusive option groups appear between parenthesis whith the different alternatives separated by a vertical bar, such as in (-a | -b -c).

If no options have been declared, this procedure returns the empty string.

4.18.1.2 Examples

# Declare some options
::Simple::Option::declare  -a
::Simple::Option::declare --b -type boolflag
::Simple::Option::declare  -c -type integer -values 2:
::Simple::Option::declare --d -type float -range 3:4
::Simple::Option::declare  -- -name ARGS

# Declare their usage
::Simple::Option::declare-usage {{O -a --b {X -c --d} {O --}}}

# Get the usage string
# This displays the following:
#   |[-a any --b (-c integer(2:) | --d float) [ARGS]]
puts [::Simple::Option::information usage]

4.18.2 Command public API

Arguments: none.

Returns: the options usage string.

4.18.3 Command further information

4.18.3.1 References

• The ::Simple::Proc::information usage procedure.

4.19 ::Simple::Option::information value option

4.19.1 Command description

Synopsis: returns an option value.

Access mode: public.

4.19.1.1 Overview

This procedure returns an option value, if available. Use ::Simple::Option::information available to assess whether an option is available or not. The option flag must be primary.

4.19.2 Command public API

Arguments:

Returns: the option value.

4.20 ::Simple::Option::information values option

4.20.1 Command description

Synopsis: returns an option number of values.

Access mode: public.

4.20.1.1 Overview

This procedure returns an option number of values. The option flag must be primary.

4.20.2 Command public API

Arguments:

Returns: the option values.

4.21 ::Simple::Option::parse commandLine

4.21.1 Command description

Synopsis: parses a command line.

Access mode: public.

4.21.1.1 Overview

This is the procedure which parses a command line and assesses its compliance against the declared command line options and their usage.

4.21.2 Command public API

Arguments:

Returns: the empty string.

4.21.3 Command further information

4.21.3.1 References

• The ::Simple::Program::parse-command-line procedure.

4.22 ::Simple::Option::reset

4.22.1 Command description

Synopsis: resets the declared options and usage information.

Access mode: public.

4.22.2 Command public API

Arguments: none.

Returns: the empty string.