File 'base/getopt.tcl' (part of 'Pool_Base')

Description (short): Option processors
Written by: Andreas Kupries
Description: Option processors useable for commandline processing, evaluation of argument lists given to vararg-procedures or evaluation of widget options.
Depends on: Tcl
Keywords: option processing, commandline processing, vararg procedures, widget options

::pool::getopt::boolean (o v)
::pool::getopt::changeDefault (optDef option newDefault)
::pool::getopt::checkValues (optDef optVal)
::pool::getopt::defAlias (optDef alias option)
::pool::getopt::defOption (optDef option args)
::pool::getopt::defShortcuts (optDef)
::pool::getopt::initValues (optDef optVal)
::pool::getopt::integer (o v)
::pool::getopt::nonempty (o v)
::pool::getopt::notype (o v)
::pool::getopt::number (o v)
::pool::getopt::parseArguments (optDef optList optVal)
::pool::getopt::process (optDef optlist optval)
::pool::getopt::processOpt (optDef optlist optval)

::pool::getopt::boolean (o v)

This type checker accepts only boolean values as recognized by the core function Tcl_GetBoolean.

Argument: o The option whose value is checked.

Argument: v The value to check.

Returns: A boolean value. True if v contained a boolean value.

::pool::getopt::changeDefault (optDef option newDefault)

Convenience procedure easing the way to change the default value of an option.

Argument: optDef The name of the array holding the option definition.

Argument: option The name of the change to change.

Argument: newDefault The new value to use as default.

::pool::getopt::checkValues (optDef optVal)

Checks the values in the given array using the type checker procedures mentioned in the definition array.

Argument: optDef The name of the array containing the option and alias definitions and their type checkers.

Argument: optVal The name of the array containing the values to check

::pool::getopt::defAlias (optDef alias option)

Convenience procedure helping in the setup of an array containing option and alias definitions. Shields users from the internal representation of an option/alias definition. This procedure places an alias definition into the array.

Argument: optDef The name of the array to place the new definition into.

Argument: alias The name of the new alias, without a preceding '-'.

Argument: option The name of the option the alias refers to, without a preceding '-'.

::pool::getopt::defOption (optDef option args)

Convenience procedure helping in the setup of an array containing option and alias definitions. Shields users from the internal representation of an option/alias definition. This procedure places an option definition into the array.

Argument: optDef The name of the array to place the new definition into.

Argument: option The name of the specified option, without a preceding '-'.

Argument: args The specification, given as <option,value>-pairs. Processed options are -type and -default.
'-type' will accept every non-empty string and defaults to ::pool::getopt::notype. The value will be interpreted later as the name of a procedure having 2 arguments and returning a boolean value. The arguments will be the name of an option and the value given to it, in this order. A result of 'false' will be interpreted as 'The value given to the option is illegal'.
'-default' will accept everything and defaults to the empty string.

::pool::getopt::defShortcuts (optDef)

Computes the full set of unique shortcuts for a given a set of option definitions and adds these as aliases to the array. Existing aliases are treated like options.

Argument: optDef The name of the array to place the shortcuts into.

::pool::getopt::initValues (optDef optVal)

Initializes the given storage array with the default values of the options in the definition array.

Argument: optDef The name of the array containing the option and alias definitions and their default values

Argument: optVal The name of the array to initalize.

::pool::getopt::integer (o v)

This type checker accepts only integer numbers.

Argument: o The option whose value is checked.

Argument: v The value to check.

Returns: A boolean value. True if v contained an integer.

::pool::getopt::nonempty (o v)

This type checker accepts every value different from the emtpy string/list

Argument: o The option whose value is checked.

Argument: v The value to check.

Returns: A boolean value. True if v was not the empty string/list.

::pool::getopt::notype (o v)

This type checker does no checking at all, it just accepts everything given to it.

Argument: o The option whose value is checked.

Argument: v The value to check.

Returns: Always true, signaling acceptance of the value in v.

::pool::getopt::number (o v)

This type checker accepts all numbers, it makes no distinction between integers and floats.

Argument: o The option whose value is checked.

Argument: v The value to check.

Returns: A boolean value. True if v contained a number.

::pool::getopt::parseArguments (optDef optList optVal)

This is the main parser procedure.

Argument: optDef The name of the array containing the option and alias definitions to recognize here.

Argument: optList The name of the variable containing the list of arguments to parse.

Argument: optVal The name of the array to hold the found values.

::pool::getopt::process (optDef optlist optval)

Parses optlist as a list of option-value pairs followed by normal arguments. The end of the option sequence is detected by the presence of arguments not beginning with '-' or the single option '--'. Only options and aliases defined in optDef are allowed. Values given to an alias are stored under the name of the option, *not* the alias. All values are stored in the array optval. The option-names are used as keys, including the '-'! The storage array is initialized with the default values of the allowed options. The moment all option values are known and not changing anymore the 'type' procedures are called with option-names and -values to determine the legality of the specified value. The return value 'False' signals an illegal value.

Argument: optDef The name of the array containing the option and alias definitions to recognize.

Argument: optlist The list of arguments to parse.

Argument: optval The name of the array to hold the found values.

Returns: A list containing the arguments not processed here.

::pool::getopt::processOpt (optDef optlist optval)

Basically the same functionality as ::pool::getopt::process, but with the following differences:
The storage array is *not* initialized with the default values.
The <optlist> must not contain arguments after the <option,value>-sequence.
There is no return value.

Argument: optDef The name of the array containing the option and alias definitions to recognize here.

Argument: optlist The list of arguments to parse.

Argument: optval The name of the array to hold the found values.

Generated by AutoDoc 2.4 at 09/14/2000, invoked by Andreas Kupries

::pool::getopt::boolean (o v)
This type checker accepts only boolean values as recognized by the core function Tcl_GetBoolean.
Argument: o	The option whose value is checked.
Argument: v	The value to check.
Returns: A boolean value. True if v contained a boolean value.

::pool::getopt::changeDefault (optDef option newDefault)
Convenience procedure easing the way to change the default value of an option.
Argument: optDef	The name of the array holding the option definition.
Argument: option	The name of the change to change.
Argument: newDefault	The new value to use as default.

::pool::getopt::checkValues (optDef optVal)
Checks the values in the given array using the type checker procedures mentioned in the definition array.
Argument: optDef	The name of the array containing the option and alias definitions and their type checkers.
Argument: optVal	The name of the array containing the values to check

::pool::getopt::defAlias (optDef alias option)
Convenience procedure helping in the setup of an array containing option and alias definitions. Shields users from the internal representation of an option/alias definition. This procedure places an alias definition into the array.
Argument: optDef	The name of the array to place the new definition into.
Argument: alias	The name of the new alias, without a preceding '-'.
Argument: option	The name of the option the alias refers to, without a preceding '-'.

::pool::getopt::defShortcuts (optDef)
Computes the full set of unique shortcuts for a given a set of option definitions and adds these as aliases to the array. Existing aliases are treated like options.
Argument: optDef	The name of the array to place the shortcuts into.

::pool::getopt::initValues (optDef optVal)
Initializes the given storage array with the default values of the options in the definition array.
Argument: optDef	The name of the array containing the option and alias definitions and their default values
Argument: optVal	The name of the array to initalize.

::pool::getopt::integer (o v)
This type checker accepts only integer numbers.
Argument: o	The option whose value is checked.
Argument: v	The value to check.
Returns: A boolean value. True if v contained an integer.

::pool::getopt::nonempty (o v)
This type checker accepts every value different from the emtpy string/list
Argument: o	The option whose value is checked.
Argument: v	The value to check.
Returns: A boolean value. True if v was not the empty string/list.

::pool::getopt::notype (o v)
This type checker does no checking at all, it just accepts everything given to it.
Argument: o	The option whose value is checked.
Argument: v	The value to check.
Returns: Always true, signaling acceptance of the value in v.

::pool::getopt::number (o v)
This type checker accepts all numbers, it makes no distinction between integers and floats.
Argument: o	The option whose value is checked.
Argument: v	The value to check.
Returns: A boolean value. True if v contained a number.

::pool::getopt::parseArguments (optDef optList optVal)
This is the main parser procedure.
Argument: optDef	The name of the array containing the option and alias definitions to recognize here.
Argument: optList	The name of the variable containing the list of arguments to parse.
Argument: optVal	The name of the array to hold the found values.

::pool::getopt::process (optDef optlist optval)
Parses optlist as a list of option-value pairs followed by normal arguments. The end of the option sequence is detected by the presence of arguments not beginning with '-' or the single option '--'. Only options and aliases defined in optDef are allowed. Values given to an alias are stored under the name of the option, not the alias. All values are stored in the array optval. The option-names are used as keys, including the '-'! The storage array is initialized with the default values of the allowed options. The moment all option values are known and not changing anymore the 'type' procedures are called with option-names and -values to determine the legality of the specified value. The return value 'False' signals an illegal value.
Argument: optDef	The name of the array containing the option and alias definitions to recognize.
Argument: optlist	The list of arguments to parse.
Argument: optval	The name of the array to hold the found values.
Returns: A list containing the arguments not processed here.

::pool::getopt::processOpt (optDef optlist optval)
Basically the same functionality as ::pool::getopt::process, but with the following differences: The storage array is not initialized with the default values. The <optlist> must not contain arguments after the <option,value>-sequence. There is no return value.
Argument: optDef	The name of the array containing the option and alias definitions to recognize here.
Argument: optlist	The list of arguments to parse.
Argument: optval	The name of the array to hold the found values.