### ===========================================================================
### -package  : SimpleType
# -version    : 0.2
# -purpose    : Types handling.
# -overview   :
#     This package allows to handle variable types.  Procedures are provided
#  to declare, delete and modify types, get information about a type and
#  obtain the list of types, as well as several others to convert between
#  different types.  The key procedure of this package is
#  K<::Simple::Type::is>, which returns whether a value conforms to a type.
#
# -usage      :
#     Types are declared via K<::Simple::Type::declare> and can be deleted via
#  K<::Simple::Type::delete> or modified via K<::Simple::Type::modify>.  The
#  K<::Simple::Type::information> procedure provides several subcommands to
#  query information about types:  K<exists>, K<declared>, K<description> and
#  K<matchingscript>.  Refer to the description of each procedure below for
#  further information.
#
#     The K<::Simple::Type::convert> set of procedures convert a value between
#  different types.  The K<::Simple::Type::is> procedure returns whether a
#  value conforms to a type.
#
# -keywords   : type decimal hexadecimal binary octal base convert
# -commands   :
#
#  * K<::Simple::Type::declare> type description ?matchingScript?
#    Declares a type.
#
#  * K<::Simple::Type::modify description> type description
#    Modifies a type description.
#
#  * K<::Simple::Type::modify matchingscript> type matchingScript
#    Modifies a type matching script.
#
#  * K<::Simple::Type::delete> type
#    Deletes a type.
#
#  * K<::Simple::Type::information declared> ?typePattern?
#    Returns the list of declared types.
#
#  * K<::Simple::Type::information exists> type
#    Returns whether a type exists.
#
#  * K<::Simple::Type::information description> type
#    Returns a type description.
#
#  * K<::Simple::Type::information matchingscript> type
#    Returns a type matching script.
#
#  * K<::Simple::Type::is> type value ?extra?
#    Returns whether a value conforms to a type.
#
#  * K<::Simple::Type::convert type> type
#    Converts a type to an unqualified name.
#
#  * K<::Simple::Type::convert flag> flag
#    Converts a flag to an unqualified name.
#
#  * K<::Simple::Type::convert optional> optional
#    Converts an optional value to an unqualified name.
#
#  * K<::Simple::Type::convert boolean> booleanExpr
#    Converts an extended boolean to its equivalent boolean value.
#
#  * K<::Simple::Type::convert dec> number
#    Converts an integer in any base to decimal.
#
#  * K<::Simple::Type::convert hex> number
#    Converts an integer in any base to hexadecimal.
#
#  * K<::Simple::Type::convert bin> number
#    Converts an integer in any base to binary.
#
#  * K<::Simple::Type::convert octal> number
#    Converts an integer in any base to octal.
#
#  * K<::Simple::Type::configure>
#    Configures the package options.
#
#  * K<::Simple::Type::cget>
#    Gets the package options.
#
# -variables  :
#  { Description      -array         {Array containing for each type its
#                                     description}}
#
# -examples   :
#
#  # Install the package
#  package require SimplePackage
#  ::Simple::Package::require-and-install SimpleType
#  
#  # Declare a type -bar which can only hold either bar or BAR
#  ::Simple::Type::declare -bar {can only hold either bar or BAR}\
#     {if {![string match $value bar] && ![string match $value BAR]}\
#     {error {}}}
#  
#  # Assert the type -bar no exists
#  # This displays the following:
#  #    The type -bar exists
#  if {[::Simple::Type::information exists -bar]} {
#     puts {The type -bar exists}
#  }
#  
#  # Get some information about the type -bar
#  # This displays the following:
#  #    The type -bar can only hold either bar or BAR
#  puts "The type -bar [::Simple::Type::information description -bar]"
#  
#  # Check the allowed contents for a variable of type -bar
#  # This displays the following:
#  #    "bar" is of type -bar
#  #    "foo" is NOT of type -bar
#  #    "BAR" is of type -bar
#  #    "bAR" is NOT of type -bar
#  foreach contents {bar foo BAR bAR} {
#     puts -nonewline "\"$contents\" is "
#     if {![::Simple::Type::is -bar $contents]} {
#        puts -nonewline {NOT }
#     }
#     puts {of type -bar}
#  }
#  
#  # Get rid of the type -bar
#  ::Simple::Type::delete -bar
#  
#  # Assert the type -bar no longer exists
#  # This displays the following:
#  #    The type -bar no longer exists
#  if {![::Simple::Type::information exists -bar]} {
#     puts {The type -bar no longer exists}
#  }
#  
#  # More fun. A compose type made of three elements:
#  # an integer, a boolean and an alphabetic
#  ::Simple::Type::declare -foo {int + boolean + alpha} {
#     foreach theType [list -int -boolean -alpha] theValue $value {
#        if {![::Simple::Type::is $theType $theValue]} {
#           error {}
#        } 
#     }
#  }
#  
#  # Check the allowed contents for a variable of type -foo
#  # This displays the following:
#  #    "2 1 bar" is of type -foo
#  #    "2 x bar" is NOT of type -foo
#  foreach contents {{2 1 bar} {2 x bar}} {
#     puts -nonewline "\"$contents\" is "
#     if {![::Simple::Type::is -foo $contents]} {
#        puts -nonewline {NOT }
#     }
#        puts {of type -foo}
#  }
#
# -todo       :
#  * It would be nice to have a procedure which guesses the type of a given
#    value.
#  * The basic name regular expression "[-_a-zA-Z0-9%]+" should be a package
#    option.  All type matching scipts requiring it should reference the
#    package option.  Alternatively, for maximum performance, upon changing
#    this option, all types matching scripts using it should be recreated.
#
# -history    :
#  19-feb-1999   Unreleased first version 0.1
#  23-apr-2000   First public release, version 0.2
#
# -copyright  :
#  Copyright (C) 1999, 2000, Juan C. Gil (jgil@gmv.es)
#
### ===========================================================================
