SimpleVariable v1.0 

 The Simple Development Library typed variables handling 

Project: the Simple Development Library.

Table of contents

1. Package description

Synopsis: the Simple Development Library typed variables handling.

Keywords: variable and type.

1.1 Overview

This package allows to handle typed variables. Typed variables not only have a name and a value if initialized, as regular Tcl variables do, but also a type and a description. Typed variables can be used as non-local (namespace or global) Tcl variables. Typed variables can be monitored to ensure their values conform to their type.

Procedures are provided to declare, delete and get information about typed variables.

1.2 Usage

Typed variables are declared via ::Simple::Variable::declare or embedded within programs (declare-program), packages (declare-package) or classes (declare-class). Upon declaration, typed variables can be optionally initialized to a value. The declaration can also specify whether a variable shall be monitored to ensure its values conform to its type. Typed variables can be deleted via ::Simple::Variable::delete. The ::Simple::Variable::information procedure provides several subcommands to query information about typed variables: exists, defaultgiven, default, type, choices, description, access and monitortype.

1.3 Examples

# Install the package
package require SimplePackage
::Simple::Package::require-and-install SimpleVariable

# Configure The Simple Development Library to store the metadata
::Simple::configure -storemetadata true

# Declare a typed variable and monitor its value
::Simple::Variable::declare foobar\ 
   -description {may contain foo or bar only}\ 
   -monitortype true -type choice -choices {foo bar}

# Get some information about the just declared variable
# This displays the following:
#   |Type: "choice"
#   |Description: "may contain foo or bar only"
puts "Type: \"[::Simple::Variable::information type foobar]\""
puts "Description: \"[::Simple::Variable::information description foobar]\""

# Set the variable to a valid value
# This displays the following:
#   |bar
set foobar bar
puts $foobar

# Set the variable to an invalid value
# This throws an error:
#    can't set "foobar": invalid value "gee" for variable
#    "::foobar" of type "choice": must be foo or bar
set foobar gee

1.4 History

1.5 Copyright

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

2. Package public API

Paradigm: procedural.

Requisites: SimpleType 1.0.

2.1 Types

None.

2.2 Options

2.2.1 -monitortype

Type: boolean.

Value: 0.

Description: whether to monitor the typed variables to ensure their values conform to their types. Notice that only those variables declared via the ::Simple::Variable::declare procedure after modifying this option are affected by the change.

2.3 Namespaces

1. ::Simple::Variable

2. ::Simple::Variable::Priv

2.4 Commands

2.4.1 ::Simple::Variable::cget ?-monitortype?

Synopsis: gets the package options.

Details: see section 4.1.

2.4.2 ::Simple::Variable::configure ?-monitortype extbool?

Synopsis: configures the package options.

Details: see section 4.2.

2.4.3 ::Simple::Variable::declare variable ?-description string? ?-monitortype extbool? ?-type type? ?-choices any-list? ?-value any?

Synopsis: declares a typed variable.

Details: see section 4.3.

2.4.4 ::Simple::Variable::delete variable

Synopsis: deletes a typed variable.

Details: see section 4.4.

2.4.5 ::Simple::Variable::information access variable

Synopsis: returns a typed variable access mode.

Details: see section 4.5.

2.4.6 ::Simple::Variable::information choices variable

Synopsis: returns a typed variable choices.

Details: see section 4.6.

2.4.7 ::Simple::Variable::information default variable

Synopsis: returns a typed variable default value.

Details: see section 4.7.

2.4.8 ::Simple::Variable::information defaultgiven variable

Synopsis: returns whether a typed variable has a default value.

Details: see section 4.8.

2.4.9 ::Simple::Variable::information description variable

Synopsis: returns a typed variable description.

Details: see section 4.9.

2.4.10 ::Simple::Variable::information exists variable

Synopsis: returns whether a typed variable exists.

Details: see section 4.10.

2.4.11 ::Simple::Variable::information monitortype variable

Synopsis: returns whether a typed variable is being monitored.

Details: see section 4.11.

2.4.12 ::Simple::Variable::information type variable

Synopsis: returns a typed variable type.

Details: see section 4.12.

2.5 Errors

2.5.1 ::Simple::Variable::IS-ARRAY

Message: variable "name" is array.

Explanation: non-array variable name could not be declared because it already exists and is an array.

Corrective action: delete the existing array.

2.5.2 ::Simple::Variable::NOT-AN-ARRAY

Message: variable "name" isn't array.

Explanation: array name could not be declared because it already exists and is not an array.

Corrective action: delete the existing non-array variable.

2.5.3 ::Simple::Variable::CANT-DELETE

Message: can't delete "name": no such variable.

Explanation: variable name could not be deleted because it does not exist.

2.5.4 ::Simple::Variable::BAD-TYPE-BOOLFLAG

Message: invalid type "boolflag" for non-flag "name".

Explanation: non-flag name type is "boolflag", but this type is only valid for flags.

Corrective action: either convert the variable or argument to a flag or modify its type.

2.5.5 ::Simple::Variable::AT-LEAST-TWO-CHOICES

Message: variable, array element or argument "name" requires at least two choices.

Explanation: variable, array element or argument name is of type "choice" or derived from it, but less than two choices were supplied.

Corrective action: supply at least two choices.

2.5.6 ::Simple::Variable::NO-CHOICES-ALLOWED

Message: no choices allowed for variable, array element or argument "name" of type "type".

Explanation: variable, array element or argument name is of type type, which is not "choice" nor derived from it, and so it does not allow the specification of choices.

2.5.7 ::Simple::Variable::NO-TYPE-CHOICE-VAR

Message: variable "name" is not of type "choice" nor "choice-list".

Explanation: the typed variable name type is not "choice" nor "choice-list".

2.5.8 ::Simple::Variable::NO-DEFAULT-VALUE

Message: variable, [incr Tk] option, argument or option "name" has no default value.

Explanation: the typed variable, [incr Tk] option, argument or option name has no default value as it was not given in its declaration.

2.5.9 ::Simple::Variable::NO-TYPE-CHOICE-ARRAY

Message: array "name" is not of type "choice-array" nor "choice-list-array".

Explanation: the typed array name type is not "choice-array" nor "choice-list-array".

2.5.10 ::Simple::Variable::MONITORING-ALIAS

Message: type monitoring for aliased variable.

Explanation: the procedure which monitors the typed variables to ensure their values conform to their types was called for a posibly correct typed variable but aliased through the use of the upvar or global commands. Due to a Tcl limitation it is then impossible to access the name of the original typed variable, and so its type, so the monitorng procedure can not proceed.

Corrective action: either deactivate the variable type monitoring or use no alias.

3. Package further information

3.1 Details

• Each typed variable internal representation is stored in one element of an array named %Variables% in the variable namespace. The name of the array element is the unqualified variable name. The array element is a list with the following elements:

3.2 Remarks

• It is possible to declare typed arrays using derived array types as in ::Simple::Variable::declare foo -type number-array. It is even possible to have an specific type for array elements by declaring them as in ::Simple::Variable::declare foo(bar) -type float. If both things are done together, all the elements in the array foo must be numbers, but the values of foo(bar) must be float numbers.

3.3 Todo

• It might be useful to be able to handle variables with more than one type so that its values must conform to one of those.

4. Package command details

4.1 ::Simple::Variable::cget ?-monitortype?

4.1.1 Command description

Synopsis: gets the package options.

Access mode: public.

4.1.2 Command public API

Arguments:

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

4.2 ::Simple::Variable::configure ?-monitortype extbool?

4.2.1 Command description

Synopsis: configures the package options.

Access mode: public.

4.2.2 Command public API

Arguments:

Returns: the empty string.

4.3 ::Simple::Variable::declare variable ?-description string? ?-monitortype extbool? ?-type type? ?-choices any-list? ?-value any?

4.3.1 Command description

Synopsis: declares a typed variable.

Access mode: public.

4.3.1.1 Overview

This procedure declares a non-local (namespace or global) typed variable or array and optionally assign a value to it.

If -type is given, the variable type is set to its parameter, otherwise the variable type is set to any.

When the variable type is choice or derived from it, -choices is required.

Use -value to initialize the typed variable to a value. This actually creates the variable.

The -monitortype flag allows to override the package option of the same name for the varible being declared. This option controls whether the variable will be monitored to ensure its values conform to its type. An error is thrown if a variable being monitored is set to a value which does not conform to its type, but the variable still contains the non-conforming value.

4.3.2 Command public API

Arguments:

Returns: the empty string.

4.3.3 Command further information

4.3.3.1 Details

The type monitoring is achieved by setting a write trace on the variable via the trace procedure with the ::Simple::Variable::Priv::trace-monitor as handler procedure. This write trace is only set for monitored variables.

4.3.3.2 Remarks

• The order of the flags is irrelevant but their parameters can not start by an hyphen.

4.4 ::Simple::Variable::delete variable

4.4.1 Command description

Synopsis: deletes a typed variable.

Access mode: public.

4.4.1.1 Overview

This procedure deletes a typed variable declared via the ::Simple::Variable::declare procedure.

4.4.2 Command public API

Arguments:

Returns: the empty string.

4.5 ::Simple::Variable::information access variable

4.5.1 Command description

Synopsis: returns a typed variable access mode.

Access mode: public.

4.5.2 Command public API

Arguments:

Returns: the typed variable access mode.

4.6 ::Simple::Variable::information choices variable

4.6.1 Command description

Synopsis: returns a typed variable choices.

Access mode: public.

4.6.2 Command public API

Arguments:

Returns: the typed variable choices.

4.7 ::Simple::Variable::information default variable

4.7.1 Command description

Synopsis: returns a typed variable default value.

Access mode: public.

4.7.2 Command public API

Arguments:

Returns: the typed variable default value.

4.7.3 Command further information

4.7.3.1 References

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

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

4.8 ::Simple::Variable::information defaultgiven variable

4.8.1 Command description

Synopsis: returns whether a typed variable has a default value.

Access mode: public.

4.8.2 Command public API

Arguments:

Returns: whether the typed variable has a default value.

4.8.3 Command further information

4.8.3.1 References

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

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

4.9 ::Simple::Variable::information description variable

4.9.1 Command description

Synopsis: returns a typed variable description.

Access mode: public.

4.9.2 Command public API

Arguments:

Returns: the typed variable description.

4.10 ::Simple::Variable::information exists variable

4.10.1 Command description

Synopsis: returns whether a typed variable exists.

Access mode: public.

4.10.2 Command public API

Arguments:

Returns: whether the typed variable exists.

4.11 ::Simple::Variable::information monitortype variable

4.11.1 Command description

Synopsis: returns whether a typed variable is being monitored.

Access mode: public.

4.11.1.1 Overview

This procedure returns whether a typed variable is being monitored to ensure its values conform to its type.

4.11.2 Command public API

Arguments:

Returns: whether the typed variable is being monitored.

4.11.3 Command further information

4.11.3.1 References

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

4.12 ::Simple::Variable::information type variable

4.12.1 Command description

Synopsis: returns a typed variable type.

Access mode: public.

4.12.2 Command public API

Arguments:

Returns: the typed variable type.