SimpleOption v1.0 

 The Simple Development Library command line options parser 

Project: the Simple Development Library.

Table of contents

1. Package description
   1.1 Overview
   1.2 Usage
   1.3 Examples
   1.4 History
   1.5 Copyright
2. Package public API
   2.1 Types
   2.2 Options
   2.3 Namespaces
   2.4 Commands
      2.4.1 ::Simple::Option::cget
      2.4.2 ::Simple::Option::configure
      2.4.3 ::Simple::Option::declare optionPair ?-name word? ?-type type? ?-range number-range? ?-choices any-list? ?-default any? ?-values decimal-range? ?-description string?
      2.4.4 ::Simple::Option::declare-usage usageGroups
      2.4.5 ::Simple::Option::information available option
      2.4.6 ::Simple::Option::information choices option
      2.4.7 ::Simple::Option::information declared
      2.4.8 ::Simple::Option::information default option
      2.4.9 ::Simple::Option::information defaultgiven option
      2.4.10 ::Simple::Option::information description option
      2.4.11 ::Simple::Option::information given option
      2.4.12 ::Simple::Option::information help
      2.4.13 ::Simple::Option::information isdefault option
      2.4.14 ::Simple::Option::information name option
      2.4.15 ::Simple::Option::information range option
      2.4.16 ::Simple::Option::information secondary option
      2.4.17 ::Simple::Option::information type option
      2.4.18 ::Simple::Option::information usage
      2.4.19 ::Simple::Option::information value option
      2.4.20 ::Simple::Option::information values option
      2.4.21 ::Simple::Option::parse commandLine
      2.4.22 ::Simple::Option::reset
   2.5 Errors
      2.5.1 ::Simple::Option::DOUBLE-HYPHEN-NOT-AS-SECONDARY
      2.5.2 ::Simple::Option::DOUBLE-HYPHEN-NOT-SECONDARY
      2.5.3 ::Simple::Option::DOUBLE-HYPHEN-REQUIRES-NAME
      2.5.4 ::Simple::Option::DOUBLE-HYPHEN-NOT-ALLOWED
      2.5.5 ::Simple::Option::ALREADY-DECLARED
      2.5.6 ::Simple::Option::ALREADY-DECLARED-AS-SECONDARY
      2.5.7 ::Simple::Option::NON-EXISTING-TYPE
      2.5.8 ::Simple::Option::NO-RANGE-ALLOWED
      2.5.9 ::Simple::Option::BAD-RANGE
      2.5.10 ::Simple::Option::VALUE-OUT-OF-RANGE
      2.5.11 ::Simple::Option::NO-VALUES-ALLOWED
      2.5.12 ::Simple::Option::USAGE-NOT-SPECIFIED
      2.5.13 ::Simple::Option::NO-NON-OPTIONAL-OPTION-IN-OPTIONAL-GROUP
      2.5.14 ::Simple::Option::NOT-ENOUGH-ALTERNATIVES-IN-EXCLUSIVE-GROUP
      2.5.15 ::Simple::Option::BAD-MAJOR-GROUP
      2.5.16 ::Simple::Option::EXCLUSIVE-GROUP-AS-ALTERNATIVE
      2.5.17 ::Simple::Option::UNDECLARED-OPTION
      2.5.18 ::Simple::Option::NOT-A-PRIMARY-OPTION
      2.5.19 ::Simple::Option::OPTIONS-EXCLUDE-EACH-OTHER
      2.5.20 ::Simple::Option::OPTION-REQUIRED
      2.5.21 ::Simple::Option::OPTION-GIVEN-REQUIRED
      2.5.22 ::Simple::Option::ONE-OF-OPTIONS-REQUIRED
      2.5.23 ::Simple::Option::OPTION-GIVEN-ONE-OF-REQUIRED
      2.5.24 ::Simple::Option::EXTRA-VALUES
      2.5.25 ::Simple::Option::TOO-MANY-OR-FEW-VALUES-1
      2.5.26 ::Simple::Option::TOO-MANY-OR-FEW-VALUES-2
      2.5.27 ::Simple::Option::VALUE-NOT-AVAILABLE
3. Package further information
   3.1 Details
   3.2 References
   3.3 Todo
4. Package command details
   4.1 ::Simple::Option::cget
      4.1.1 Command description
      4.1.2 Command public API
   4.2 ::Simple::Option::configure
      4.2.1 Command description
      4.2.2 Command public API
   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
         4.3.1.1 Overview
      4.3.2 Command public API
   4.4 ::Simple::Option::declare-usage usageGroups
      4.4.1 Command description
         4.4.1.1 Overview
      4.4.2 Command public API
   4.5 ::Simple::Option::information available option
      4.5.1 Command description
         4.5.1.1 Overview
      4.5.2 Command public API
   4.6 ::Simple::Option::information choices option
      4.6.1 Command description
         4.6.1.1 Overview
      4.6.2 Command public API
   4.7 ::Simple::Option::information declared
      4.7.1 Command description
         4.7.1.1 Overview
      4.7.2 Command public API
   4.8 ::Simple::Option::information default option
      4.8.1 Command description
         4.8.1.1 Overview
      4.8.2 Command public API
      4.8.3 Command further information
         4.8.3.1 References
   4.9 ::Simple::Option::information defaultgiven option
      4.9.1 Command description
      4.9.2 Command public API
      4.9.3 Command further information
         4.9.3.1 References
   4.10 ::Simple::Option::information description option
      4.10.1 Command description
         4.10.1.1 Overview
      4.10.2 Command public API
   4.11 ::Simple::Option::information given option
      4.11.1 Command description
         4.11.1.1 Overview
      4.11.2 Command public API
      4.11.3 Command further information
         4.11.3.1 References
   4.12 ::Simple::Option::information help
      4.12.1 Command description
         4.12.1.1 Overview
      4.12.2 Command public API
   4.13 ::Simple::Option::information isdefault option
      4.13.1 Command description
         4.13.1.1 Overview
      4.13.2 Command public API
      4.13.3 Command further information
         4.13.3.1 References
   4.14 ::Simple::Option::information name option
      4.14.1 Command description
         4.14.1.1 Overview
      4.14.2 Command public API
   4.15 ::Simple::Option::information range option
      4.15.1 Command description
         4.15.1.1 Overview
      4.15.2 Command public API
   4.16 ::Simple::Option::information secondary option
      4.16.1 Command description
         4.16.1.1 Overview
      4.16.2 Command public API
   4.17 ::Simple::Option::information type option
      4.17.1 Command description
         4.17.1.1 Overview
      4.17.2 Command public API
   4.18 ::Simple::Option::information usage
      4.18.1 Command description
         4.18.1.1 Overview
         4.18.1.2 Examples
      4.18.2 Command public API
      4.18.3 Command further information
         4.18.3.1 References
   4.19 ::Simple::Option::information value option
      4.19.1 Command description
         4.19.1.1 Overview
      4.19.2 Command public API
   4.20 ::Simple::Option::information values option
      4.20.1 Command description
         4.20.1.1 Overview
      4.20.2 Command public API
   4.21 ::Simple::Option::parse commandLine
      4.21.1 Command description
         4.21.1.1 Overview
      4.21.2 Command public API
      4.21.3 Command further information
         4.21.3.1 References
   4.22 ::Simple::Option::reset
      4.22.1 Command description
      4.22.2 Command public API

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:

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

1.4 History

Date Reason
10-sep-2001 First public release, version 0.4
17-feb-2003 Second public release, version 0.5
30-mar-2003 Extra package, version 0.5.1
11-jul-2003 Package renamed to SimpleOption, version 0.5.2
22-jun-2005 The Simple Development Library version 1.0

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

3.3 Todo

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:

Argument Type Default value/ choices Description
optionPair flag-list (n/a) Primary option flag and optional secondary flag
?-name? word (n/a) Option name
?-type? type any Option values type
?-range? number-range : Option values numeric range
?-choices? any-list (empty string) List of choices for choice type and its derivations
?-default? any (n/a) Option default value
?-values? decimal-range 1 Number of values range
?-description? string (empty string) Option description

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:

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

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:

Argument Type Default value/ choices Description
usageGroups list (n/a) Usage option groups

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:

Argument Type Default value/ choices Description
option flag (n/a) Option flag

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:

Argument Type Default value/ choices Description
option flag (n/a) Option flag

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:

Argument Type Default value/ choices Description
option flag (n/a) Option flag

Returns: the option default value.

4.8.3 Command further information

4.8.3.1 References

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:

Argument Type Default value/ choices Description
option flag (n/a) Option flag

Returns: whether the option has default value.

4.9.3 Command further information

4.9.3.1 References

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:

Argument Type Default value/ choices Description
option flag (n/a) Option flag

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:

Argument Type Default value/ choices Description
option flag (n/a) Option flag

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

4.11.3 Command further information

4.11.3.1 References

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:

Argument Type Default value/ choices Description
option flag (n/a) Option flag

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

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:

Argument Type Default value/ choices Description
option flag (n/a) Option flag

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:

Argument Type Default value/ choices Description
option flag (n/a) Option flag

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:

Argument Type Default value/ choices Description
option flag (n/a) Option flag

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:

Argument Type Default value/ choices Description
option flag (n/a) Option flag

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

4.18.2 Command public API

Arguments: none.

Returns: the options usage string.

4.18.3 Command further information

4.18.3.1 References

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:

Argument Type Default value/ choices Description
option flag (n/a) Option flag

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:

Argument Type Default value/ choices Description
option flag (n/a) Option flag

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:

Argument Type Default value/ choices Description
commandLine list (n/a) Command line

Returns: the empty string.

4.21.3 Command further information

4.21.3.1 References

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.