### ===========================================================================
### -package  : SimpleExtVar
# -version    : 0.2
# -purpose    : Extended format variables handling.
# -overview   :
#     This package allows to handle extended format variables.  Extended
#  variables have not only a name and a value, but also a type and a
#  description, and can be used as non-local Tcl variables or as extended
#  procedure arguments as provided by the SimpleExtProc package.
#
#     Procedures are provided to create, delete and get information about an
#  extended variable, as well as others to convert between extended and Tcl
#  canonical procedure argument formats.
#
# -usage      :
#     Extended format variables are created via P<::Simple::ExtVar::create>. 
#  The declaration specifies whether each variable shall be monitored to
#  ensure its value conforms to its type.  Extended variables can be deleted
#  via K<::Simple::ExtVar::delete>.  The K<::Simple::ExtVar::information>
#  procedure provides several subcommands to query information about extended
#  variables:  K<exists>, K<type>, K<choices>, K<description> and
#  K<monitortype>.  Refer to the description of each procedure below for
#  further information.
#
#     The K<::Simple::ExtVar::convert> pair of procedures convert between
#  extended and Tcl canonical procedure argument formats.
#
#     The extended variables format is very similar to that of the arguments
#  used by the P<opt> package distributed with Tcl 8.0:  {name type ?value? 
#  description}.  There, "name" is the variable name, "type" its type, "value"
#  its value (actual or default, depending on whether we are handling a
#  variable or a procedure argument) and "description" a string describing the
#  variable.
#
#  H2<Variable name>
#
#     This is the variable name.  It must conform to the I<-name> Simple
#  Library type (except for flags and optional arguments, see below).
#
#     Variables whose name starts by a hyphen are flags.  They are allowed
#  when the variable is intended as a procedure argument and indicates that
#  their presence in the procedure call actual argument list is optional. 
#  Variables whose name is enclosed between question marks are optional and
#  are also allowed in argument lists only.  Both the flags and the optional
#  arguments are further described in the P<proc-ext> procedure of the
#  SimpleExtProc package.
#
#  H2<Variable type>
#
#     The variable type must be a type known by the Simple library, that is,
#  any Simple library type or added via the P<::Simple::Type::add> procedure. 
#  Some types are only allowed when the variable is intended as a procedure
#  argument and is thus further described in the P<proc-ext> procedure of the
#  SimpleExtProc package.
#
#  H2<Variable value>
#
#     A variable declaration via the P<::Simple::ExtVar::create> procedure
#  must specify a value.  If the variable type is I<-choice> the value is the
#  first element of the choices list.  When the variable is intended as a
#  procedure argument, this field is regarded as the default value for the
#  variable, which must be optional.  Again, see the P<proc-ext> procedure of
#  the SimpleExtProc package for details.
#
#  H2<Variable description>
#
#     This is simply a description of the variable.
#
# -keywords   : extended variable type
# -variables  :
#
#  { Variables        -array         {Array containing for each extended format
#                                     variable its internal representation}}
#  { MonitorType      -int 1         {Stores the value of the I<-monitortype>
#                                     package option}}
#
# -commands   :
#
#  * K<::Simple::ExtVar::create> ?-monitortype extbool? extended
#    Creates a non-local extended format variable.
#
#  * K<::Simple::ExtVar::delete> variable
#    Deletes a non-local extended format variable.
#
#  * K<::Simple::ExtVar::convert canonical> extended
#    Converts a variable from extended to canonical format.
#
#  * K<::Simple::ExtVar::convert extended> canonical
#    Converts a variable from canonical to extended format.
#
#  * K<::Simple::ExtVar::information exists> variable
#    Returns whether an extended format variable exists.
#
#  * K<::Simple::ExtVar::information type> variable
#    Returns an extended format variable type.
#
#  * K<::Simple::ExtVar::information choices> variable
#    Returns an extended format variable choices.
#
#  * K<::Simple::ExtVar::information description> variable
#    Returns an extended format variable description.
#
#  * K<::Simple::ExtVar::information monitortype> variable
#    Returns whether an extended format variable is being monitored.
#
#  * K<::Simple::ExtVar::configure> ?-monitortype extbool?
#    Configures the package options.
#
#  * K<::Simple::ExtVar::cget> ?-monitortype?
#    Gets the package options.
#
# -options    :
#
#  * I<-monitortype>:  whether to monitor the extended variables to ensure
#    their values conform to their types.  Notice that only those variables
#    created via the P<::Simple::ExtVar::create> procedure B<after> modifying
#    this option are affected by the change.
#
# -examples   :
#
#  # Install the package
#  package require SimplePackage
#  ::Simple::Package::require-and-install SimpleExtVar
#  
#  # Create an extended variable and monitor its value
#  ::Simple::ExtVar::create -monitortype true\
#     {foobar -choice {foo bar} {may contain foo or bar only}}
#  
#  # Get some information about the just created variable
#  # This displays the following:
#  #    Variable foobar is equal to: foo
#  #    Type: "-choice"
#  #    Description: "may contain foo or bar only"
#  puts "Variable foobar is equal to: $foobar"
#  puts "Type: \"[::Simple::ExtVar::information type foobar]\""
#  puts "Description: \"[::Simple::ExtVar::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
#  #    type "-choice": must be foo or bar
#  set foobar gee
#
# -details    : 
#     The extended format variables internal representation contained in the
#  I<Variables> namespace array is a list with the following elements:
#     0: variable type
#     1: variable choices (empty if type is not "-choice")
#     2: variable description
#
# -bugs       :
#  * When a namespace is deleted, the extended format variables therein are
#    not fully deleted.  This is because the state of the extended format
#    variables is stored in arrays in the ::Simple::ExtVar namespace instead
#    in the variable namespace.
#
# -history    :
#  23-apr-2000   First public release, version 0.2
#
# -copyright  :
#  Copyright (C) 1999, 2000, Juan C. Gil (jgil@gmv.es)
#
### ===========================================================================
