SimpleError v1.0
The Simple Development Library error handling
Project: the Simple Development Library.
::Simple::Error::catch-explain
script ?variableName?::Simple::Error::cget
::Simple::Error::configure
::Simple::Error::declare
errorCode ?-message formatstring? ?-explanation string? ?-corrective string? ?-explained string? ?-translation string?::Simple::Error::delete
errorCode::Simple::Error::explain
errorCode::Simple::Error::information corrective
errorCode::Simple::Error::information declared
?pattern?::Simple::Error::information exists
errorCode::Simple::Error::information explained
errorCode::Simple::Error::information explanation
errorCode::Simple::Error::information message
errorCode::Simple::Error::throw
?-extra string? errorCode args::Simple::Error::FORMAT-ERROR
::Simple::Error::UNDECLARED-ERROR
::Simple::Error::catch-explain
script ?variableName?::Simple::Error::cget
::Simple::Error::configure
::Simple::Error::declare
errorCode ?-message formatstring? ?-explanation string? ?-corrective string? ?-explained string? ?-translation string?::Simple::Error::delete
errorCode::Simple::Error::explain
errorCode::Simple::Error::information corrective
errorCode::Simple::Error::information declared
?pattern?::Simple::Error::information exists
errorCode::Simple::Error::information explained
errorCode::Simple::Error::information explanation
errorCode::Simple::Error::information message
errorCode::Simple::Error::throw
?-extra string? errorCode argsSynopsis: the Simple Development Library error handling.
Keywords: error, catch, explain and throw.
This package allows to handle errors.
In its simplest form, an error is an error code and an error message. The error code has the form of a Tcl qualified name and is used for indexing the error. The error message is a format string in the sense of the format
Tcl command used for formatting the actual error message with parameters when thrown.
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.
Errors are declared via ::Simple::Error::declare
or embedded within programs (declare-program
), packages (declare-package
) or classes (declare-class
). The error code and error message are compulsory while the error explanation, corrective action, translation string and explained error message, used by ::Simple::Error::explain
to explain an error, are optional.
Declared errors can be thrown via ::Simple::Error::throw
and explained via ::Simple::Error::explain
. The error code of thrown errors (as reported by the ::errorCode variable) is the error code (with the form of a qualified name) given to the error upon declaration. ::Simple::Error::throw
accepts an -extra argument that, if given, makes the ::errorCode of the thrown error a two element list where the first element is the error code of the declared error and the second is the parameter of the -extra flag.
The ::Simple::Error::information
procedure provides several subcommands to query information about declared errors: exists
, declared
, message
, explanation
, corrective
and explained
.
::Simple::Error::catch-explain
is similar to the catch
command but explains any declared error the evaluated script may throw.
Finally, use ::Simple::Error::delete
to delete a declared error.
# Install the package package require SimpleError package require SimpleError-extra # Let's store the error details ::Simple::configure -storemetadata true # Declare an error ::Simple::Error::declare { FILE-NOT-FOUND } -message { no file named %s in directory %s } -explanation { There is no file named <file> in directory <dir> } -corrective { Make sure both the file and directory are correct } # The error is now declared # This displays the following: # |1 puts [::Simple::Error::information exists FILE-NOT-FOUND] # 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: # |no file named foo.tcl in directory /usr/home/ # | ===================== 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> # | Corrective action: 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 declared anymore # This displays the following: # |0 puts [::Simple::Error::information exists FILE-NOT-FOUND]
Date | Reason |
23-apr-2000 | First public release, version 0.2 |
10-sep-2001 | Second public release, version 0.4 |
17-feb-2003 | Third public release, version 0.5 |
09-mar-2003 | ::Simple::Error::explain returns a list, version 0.5.1 |
22-mar-2003 | Added -message to ::Simple::Error::declare , version 0.5.2 |
07-sep-2004 | Bug 7 correction, version 0.5.3 |
28-oct-2004 | Error codes can be unqualified, version 0.5.4 |
22-jun-2005 | The Simple Development Library version 1.0 |
Copyright (C) 1999-2005, Juan C. Gil (jgil@gmv.es).
Paradigm: procedural.
Requisites: SimpleBase 1.0
.
Description: error code: ::Simple::Error::FORMAT-ERROR, ...
None.
::Simple::Error
::Simple::Error::Priv
::Simple::Error::catch-explain
script ?variableName?Synopsis: catches an error and explains it.
Details: see section 4.1.
::Simple::Error::cget
Synopsis: gets the package options.
Details: see section 4.2.
::Simple::Error::configure
Synopsis: configures the package options.
Details: see section 4.3.
::Simple::Error::declare
errorCode ?-message formatstring? ?-explanation string? ?-corrective string? ?-explained string? ?-translation string?Synopsis: declares an error.
Details: see section 4.4.
::Simple::Error::delete
errorCodeSynopsis: deletes an error.
Details: see section 4.5.
::Simple::Error::explain
errorCodeSynopsis: explains an error.
Details: see section 4.6.
::Simple::Error::information corrective
errorCodeSynopsis: returns an error corrective action.
Details: see section 4.7.
::Simple::Error::information declared
?pattern?Synopsis: returns the list of declared errors.
Details: see section 4.8.
::Simple::Error::information exists
errorCodeSynopsis: returns whether an error has been declared.
Details: see section 4.9.
::Simple::Error::information explained
errorCodeSynopsis: returns an error explained error message.
Details: see section 4.10.
::Simple::Error::information explanation
errorCodeSynopsis: returns an error explanation.
Details: see section 4.11.
::Simple::Error::information message
errorCodeSynopsis: returns an error message format string.
Details: see section 4.12.
::Simple::Error::throw
?-extra string? errorCode argsSynopsis: throws an error.
Details: see section 4.13.
::Simple::Error::FORMAT-ERROR
Message: error formatting error "error code" (error message is {error message}, arguments are {arguments}).
Explanation: an error ocurred when formatting error error code, whose error message is error message, with run-time arguments arguments.
Corrective action: check the error message format and the number of run-time arguments. Check in particular that the -explanation contains the same number of items between brackets than format specifiers ("%s", "%d", ...) in the error message.
::Simple::Error::UNDECLARED-ERROR
Message: undeclared error "error code".
Explanation: error error code has not been declared.
Corrective action: use ::Simple::Error::declare
to declare the error.
Each declared error internal representation is stored in one element of an array named %Errors% in the namespace pointed to by the error code namespace qualifiers. The name of the array element is the error code unqualified name. The array element is a list with the following elements (only the first is compulsory):
0 | error message format string |
1 | error explanation |
2 | error corrective action |
3 | error explained error message |
4 | error translation string |
Provide a ::Simple::Error::modify
procedure.
::Simple::Error::catch-explain
script ?variableName?Synopsis: catches an error and explains it.
Access mode: public.
This procedure is similar to the catch
command. It evaluates the given script catching any error it may throw. If the script throws a declared error, the ::errorInfo variable is modified to include an explanation of the error. Otherwise, the procedure acts exactly as catch
except that the call to this procedure is deleted from ::errorInfo.
Arguments:
Argument | Type | Default value/ choices | Description |
script | script | (n/a) | Script to evaluate |
?variableName? | variablename | (n/a) | Name of the variable in the calling scope in which the script evaluation result is to be placed |
Returns: the result of the evaluated script.
Effects:
Those of the evaluated script.
::Simple::Error::cget
Synopsis: gets the package options.
Access mode: public.
Arguments: none.
Returns: the requested option value or the whole list of options if none specified.
::Simple::Error::configure
Synopsis: configures the package options.
Access mode: public.
Arguments: none.
Returns: the "package with no options" error is thrown.
::Simple::Error::declare
errorCode ?-message formatstring? ?-explanation string? ?-corrective string? ?-explained string? ?-translation string?Synopsis: declares an error.
Access mode: public.
This procedure is used to declare a new error.
An error is made of six elements:
the error code,
the error messsage format string,
the error explanation,
the corrective action,
the explained error message and
the error translation string.
The first two are compulsory while the last four are optional.
The error code must be a Tcl name. The qualifiers point to the namespace in which the error information will be stored; the namespace must exist; if the error code is unqualified, it is qualified in the calling scope. The unqualified name is the actual code of the error to be thrown via ::Simple::Error::throw
. The error message is a format string as accepted by the format
command. This format string is used by ::Simple::Error::throw
to format the error message.
The error explanation, corrective action, explained error message and translation string are used by ::Simple::Error::explain
.
Arguments:
Argument | Type | Default value/ choices | Description |
errorCode | errorcode | (n/a) | Error code |
?-message? | formatstring | (empty string) | Error message format string |
?-explanation? | string | (empty string) | Error explanation |
?-corrective? | string | (empty string) | Corrective action |
?-explained? | string | (empty string) | Explained error message |
?-translation? | string | (empty string) | Translation string |
Returns: the empty string.
The order of the flags is irrelevant but their parameters can not start by an hyphen.
::Simple::Error::delete
errorCodeSynopsis: deletes an error.
Access mode: public.
Arguments:
Argument | Type | Default value/ choices | Description |
errorCode | errorcode | (n/a) | Error code |
Returns: the empty string.
::Simple::Error::explain
errorCodeSynopsis: explains an error.
Access mode: public.
This procedure explains an error previously declared via ::Simple::Error::declare
.
If The Simple Development Library -storemetadata option was not set or no error explanation was provided when the error was declared, the empty string is returned; otherwise the full error explanation is returned as a three elements list.
If the explained error message was provided when the error was declared, it is used. Otherwise it is composed from the unexplained error message with the format specifiers substituted by the name of the error run-time arguments they represent. The list of the run-time arguments are extracted from the error explanation, in which they appear as strings between angle brackets. For example, if the error message is
"no file named %s in directory %s"
an appropriate error explanation would be
"the file named <file> in directory <directory> could not be found",
so that the error message included in this procedure return value would be
"no file named <file> in directory <directory>".
The translation string argument of ::Simple::Error::declare
is used here when the order in which the run-time arguments appear in the error explanation is different from their order in the error message. In this case, the translation string is a sequence of items between angle brackets which correspond to the names of the error message run-time arguments.
# Let's store the error details ::Simple::configure -storemetadata true # Declare an error ::Simple::Error::declare { FILE-NOT-FOUND-1 } -message { no file named %s in directory %s } -explanation { There is no file named <file> in directory <dir> } -corrective { Make sure both the file and directory are correct } # Explain the error # This displays the following: # |FILE-NOT-FOUND-1 # |no file named <file> in directory <dir> # |There is no file named <file> in directory <dir>. # |Make sure both the file and directory are correct. foreach line [::Simple::Error::explain FILE-NOT-FOUND-1] {puts $line} # Declare another error ::Simple::Error::declare { FILE-NOT-FOUND-2 } -message { directory %s has no file named %s } -explanation { There is no file named <file> in directory <dir> } -corrective { Make sure both the file and directory are correct } {<dir> <file>} # Explain the error # This displays the following: # |FILE-NOT-FOUND-2 # |directory <dir> has no file named <file> # |There is no file named <file> in directory <dir>. # |Make sure both the file and directory are correct. foreach line [::Simple::Error::explain FILE-NOT-FOUND-2] {puts $line} # Declare another error ::Simple::Error::declare { FILE-NOT-FOUND-3 } -message { directory %s has no file named %s } -explanation { There is no file named <file> nor <file>.BACKUP in directory <dir> } -corrective { Make sure both the file and directory are correct } -explained { directory <dir> has no file named <file> or <file>.BACKUP } # Explain the error # This displays the following: # |FILE-NOT-FOUND-3 # |directory <dir> has no file named <file> or <file>.BACKUP # |There is no file named <file> in directory <dir>. # |Make sure both the file and directory are correct. foreach line [::Simple::Error::explain FILE-NOT-FOUND-3] {puts $line}
Arguments:
Argument | Type | Default value/ choices | Description |
errorCode | errorcode | (n/a) | Error code |
Returns: a list with the following elements:
0 | the explained error message, or unexplained if the error explanation is not available. |
1 | the error explanation, or the empty string if not available. |
2 | the corrective action, or the empty string if not available. |
::Simple::Error::information corrective
errorCodeSynopsis: returns an error corrective action.
Access mode: public.
This procedure returns a declared error corrective action.
Arguments:
Argument | Type | Default value/ choices | Description |
errorCode | errorcode | (n/a) | Error code |
Returns: the error corrective action.
::Simple::Error::information declared
?pattern?Synopsis: returns the list of declared errors.
Access mode: public.
This procedure returns the list of declared errors matching the given pattern.
Arguments:
Argument | Type | Default value/ choices | Description |
?pattern? | pattern | (empty string) | Pattern |
Returns: the list of declared errors matching the given pattern.
Use no pattern to obtain the complete list of declared errors.
::Simple::Error::information exists
errorCodeSynopsis: returns whether an error has been declared.
Access mode: public.
Arguments:
Argument | Type | Default value/ choices | Description |
errorCode | errorcode | (n/a) | Error code |
Returns: whether the error has been declared.
::Simple::Error::information explained
errorCodeSynopsis: returns an error explained error message.
Access mode: public.
This procedure returns a declared error explained error message.
Arguments:
Argument | Type | Default value/ choices | Description |
errorCode | errorcode | (n/a) | Error code |
Returns: the error explained error message.
::Simple::Error::information explanation
errorCodeSynopsis: returns an error explanation.
Access mode: public.
This procedure returns a declared error explanation.
Arguments:
Argument | Type | Default value/ choices | Description |
errorCode | errorcode | (n/a) | Error code |
Returns: the error explanation.
::Simple::Error::information message
errorCodeSynopsis: returns an error message format string.
Access mode: public.
This procedure returns a declared error message format string.
Arguments:
Argument | Type | Default value/ choices | Description |
errorCode | errorcode | (n/a) | Error code |
Returns: the error message format string.
::Simple::Error::throw
?-extra string? errorCode argsSynopsis: throws an error.
Access mode: public.
This procedure throws a declared error.
Arguments:
Argument | Type | Default value/ choices | Description |
?-extra? | string | (empty string) | Extra data |
errorCode | errorcode | (n/a) | Error code |
args | list | (n/a) | Error run-time arguments |
Returns: none; the error is thrown.
Effects:
The error is thrown.