### ===========================================================================
### -package  : SimpleError
# -version    : 0.2
# -purpose    : Error handling.
# -overview   : 
#     This package centralizes the handling of errors.  A declared error is
#  made of five elements:  the error code, the error messsage, the error
#  explanation, the corrective action and a translation string.  Procedures
#  are provided to declare, delete, throw and explain errors, get information
#  about an error, obtain the list of errors and catch errors explaining them.
#
# -usage      :
#     Errors are declared via K<::Simple::Error::declare>.  An error code and
#  error message are mandatory while the error explanation, corrective action,
#  translation string and explained error message, which are used by
#  K<::Simple::error::explain> to explain an error, are optional.  In fact
#  these optional error attributes are ignored (that is, not stored) unless
#  the store details package option is true (this option is false by default).
#
#     Declared errors can be thrown via K<::Simple::Error::throw> and
#  explained via K<::Simple::Error::explain>.  The
#  K<::Simple::Package::information> procedure provides several subcommands to
#  query information about declared errors:  K<exists>, K<message>,
#  K<explanation> and K<corrective>.  Refer to the description of each
#  procedure below for further information.
#
#     The K<::Simple::Error::catch-explain> is similar to the K<catch>
#  command but explains any declared error the evaluated script may throw.
#
#  Use K<::Simple::Error::delete> to delete a declared error.
#
# -keywords   : error catch explain throw
# -commands   :
#
#  * K<::Simple::Error::declare> errorCode errorMessage errorExplanation
#    ?correctiveAction? ?translation? ?explainedErrorMessage?
#    Declares an error.
#
#  * K<::Simple::Error::delete> errorCode
#    Deletes an error.
#
#  * K<::Simple::Error::information declared> ?pattern?
#    Returns the list of declared errors.
#
#  * K<::Simple::Error::information exists> errorCode
#    Returns whether an error has been declared.
#
#  * K<::Simple::Error::information message> errorCode
#    Returns an error message format string.
#
#  * K<::Simple::Error::information explanation> errorCode
#    Returns an error explanation text.
#
#  * K<::Simple::Error::information corrective> errorCode
#    Returns an error corrective action text.
#
#  * K<::Simple::Error::information explained> errorCode
#    Returns an error explained error message.
#
#  * K<::Simple::Error::explain> errorCode
#    Explains an error.
#
#  * K<::Simple::Error::throw> errorCode ?args?
#    Throws an error.
#
#  * K<::Simple::Error::catch-explain> script ?variableName?
#    Catches an error and explains it.
#
#  * K<::Simple::Error::configure> ?-storedetails extbool?
#    Configures the package options.
#
#  * K<::Simple::Error::cget> ?-storedetails?
#    Gets the package options.
#
# -variables  :
#
#  { StoreDetails     -boolean 0     {Stores the value of the I<-storedetails>
#                                     package option}}
#
# -options    :
#
#  * I<-storedetails>:  whether the error details (error explanation,
#    corrective action and explained error message) of errors declared via
#    K<::Simple::Error::declare> are stored or not.  While not storing the
#    error details saves some memory, the K<::Simple::Error::explain>
#    procedure is really only useful for errors with stored details.  Notice
#    that only those errors declared B<after> modyfing this option are
#    affected by the change.
#
# -examples   :
#
#  # Install the package
#  package require SimpleError
#
#  # Set the package option to store the error details
#  ::Simple::Error::configure -storedetails true
#
#  # Declare an error
#  ::Simple::Error::declare FILE-NOT-FOUND {
#     no file named %s in directory %s
#  } {
#     There is no file named <file> in directory <dir>
#  } {
#     Make sure both the file and directory are correct
#  }
#
#  # Get the error correction action
#  # This displays the following:
#  #    Make sure both the file and directory are correct
#  puts [::Simple::Error::information corrective FILE-NOT-FOUND]
#
#  # Throw the error, then catch and explain it
#  # This displays the following:
#  #    ===================== Error explanation ======================
#  #    Error code   : FILE-NOT-FOUND
#  #    Error message: no file named <file> in directory <dir>
#  #    Explanation  : There is no file named <file> in directory <dir>.
#  #    Correction   : Make sure both the file and directory are correct.
#  #    ================== End of error explanation ==================
#  ::Simple::Error::catch-explain {
#     ::Simple::Error::throw FILE-NOT-FOUND foo.tcl /usr/home/
#     } result
#  puts $::errorInfo
#
#  # Delete the error
#  ::Simple::Error::delete FILE-NOT-FOUND
#
#  # The error is not decalred anymore
#  # This displays the following:
#  #    0
#  puts [::Simple::Error::information exists FILE-NOT-FOUND]
#
# -details    : 
#  * Each declared error is stored in an element of an array named V<Errors>
#    in the namespace pointed to by the error code namespace qualifiers.  The
#    name of the array element is the error code tail.  The array element is a
#    list with the following elements (only the first is customary):
#     0: error message format string
#     1: error explanation text
#     2: error corrective action text
#     3: error translation string
#
# -todo       :
#  * Provide a K<::Simple::Error::modify> procedure.
#
# -history    :
#  23-apr-2000   First public release, version 0.2
#
# -copyright  :
#  Copyright (C) 1999, 2000, Juan C. Gil (jgil@gmv.es)
#
### ===========================================================================
