SimpleError v1.0 

 The Simple Development Library error handling 

Project: the Simple Development Library.

Table of contents

1. Package description

Synopsis: the Simple Development Library error handling.

Keywords: error, catch, explain and throw.

1.1 Overview

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.

1.2 Usage

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.

1.3 Examples

# 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]

1.4 History

1.5 Copyright

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

2. Package public API

Paradigm: procedural.

Requisites: SimpleBase 1.0.

2.1 Types

2.1.1 errorcode

Description: error code: ::Simple::Error::FORMAT-ERROR, ...

2.2 Options

None.

2.3 Namespaces

1. ::Simple::Error

2. ::Simple::Error::Priv

2.4 Commands

2.4.1 ::Simple::Error::catch-explain script ?variableName?

Synopsis: catches an error and explains it.

Details: see section 4.1.

2.4.2 ::Simple::Error::cget

Synopsis: gets the package options.

Details: see section 4.2.

2.4.3 ::Simple::Error::configure

Synopsis: configures the package options.

Details: see section 4.3.

2.4.4 ::Simple::Error::declare errorCode ?-message formatstring? ?-explanation string? ?-corrective string? ?-explained string? ?-translation string?

Synopsis: declares an error.

Details: see section 4.4.

2.4.5 ::Simple::Error::delete errorCode

Synopsis: deletes an error.

Details: see section 4.5.

2.4.6 ::Simple::Error::explain errorCode

Synopsis: explains an error.

Details: see section 4.6.

2.4.7 ::Simple::Error::information corrective errorCode

Synopsis: returns an error corrective action.

Details: see section 4.7.

2.4.8 ::Simple::Error::information declared ?pattern?

Synopsis: returns the list of declared errors.

Details: see section 4.8.

2.4.9 ::Simple::Error::information exists errorCode

Synopsis: returns whether an error has been declared.

Details: see section 4.9.

2.4.10 ::Simple::Error::information explained errorCode

Synopsis: returns an error explained error message.

Details: see section 4.10.

2.4.11 ::Simple::Error::information explanation errorCode

Synopsis: returns an error explanation.

Details: see section 4.11.

2.4.12 ::Simple::Error::information message errorCode

Synopsis: returns an error message format string.

Details: see section 4.12.

2.4.13 ::Simple::Error::throw ?-extra string? errorCode args

Synopsis: throws an error.

Details: see section 4.13.

2.5 Errors

2.5.1 ::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.

2.5.2 ::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.

3. Package further information

3.1 Details

• 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):

3.2 Todo

• Provide a ::Simple::Error::modify procedure.

4. Package command details

4.1 ::Simple::Error::catch-explain script ?variableName?

4.1.1 Command description

Synopsis: catches an error and explains it.

Access mode: public.

4.1.1.1 Overview

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.

4.1.2 Command public API

Arguments:

Returns: the result of the evaluated script.

Effects:

• Those of the evaluated script.

4.2 ::Simple::Error::cget

4.2.1 Command description

Synopsis: gets the package options.

Access mode: public.

4.2.2 Command public API

Arguments: none.

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

4.3 ::Simple::Error::configure

4.3.1 Command description

Synopsis: configures the package options.

Access mode: public.

4.3.2 Command public API

Arguments: none.

Returns: the "package with no options" error is thrown.

4.4 ::Simple::Error::declare errorCode ?-message formatstring? ?-explanation string? ?-corrective string? ?-explained string? ?-translation string?

4.4.1 Command description

Synopsis: declares an error.

Access mode: public.

4.4.1.1 Overview

This procedure is used to declare a new error.

An error is made of six elements:

1. the error code,

2. the error messsage format string,

3. the error explanation,

4. the corrective action,

5. the explained error message and

6. 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.

4.4.2 Command public API

Arguments:

Returns: the empty string.

4.4.3 Command further information

4.4.3.1 Remarks

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

4.5 ::Simple::Error::delete errorCode

4.5.1 Command description

Synopsis: deletes an error.

Access mode: public.

4.5.2 Command public API

Arguments:

Returns: the empty string.

4.6 ::Simple::Error::explain errorCode

4.6.1 Command description

Synopsis: explains an error.

Access mode: public.

4.6.1.1 Overview

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.

4.6.1.2 Examples

# 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}

4.6.2 Command public API

Arguments:

Returns: a list with the following elements:

4.7 ::Simple::Error::information corrective errorCode

4.7.1 Command description

Synopsis: returns an error corrective action.

Access mode: public.

4.7.1.1 Overview

This procedure returns a declared error corrective action.

4.7.2 Command public API

Arguments:

Returns: the error corrective action.

4.8 ::Simple::Error::information declared ?pattern?

4.8.1 Command description

Synopsis: returns the list of declared errors.

Access mode: public.

4.8.1.1 Overview

This procedure returns the list of declared errors matching the given pattern.

4.8.2 Command public API

Arguments:

Returns: the list of declared errors matching the given pattern.

4.8.3 Command further information

4.8.3.1 Remarks

• Use no pattern to obtain the complete list of declared errors.

4.9 ::Simple::Error::information exists errorCode

4.9.1 Command description

Synopsis: returns whether an error has been declared.

Access mode: public.

4.9.2 Command public API

Arguments:

Returns: whether the error has been declared.

4.10 ::Simple::Error::information explained errorCode

4.10.1 Command description

Synopsis: returns an error explained error message.

Access mode: public.

4.10.1.1 Overview

This procedure returns a declared error explained error message.

4.10.2 Command public API

Arguments:

Returns: the error explained error message.

4.11 ::Simple::Error::information explanation errorCode

4.11.1 Command description

Synopsis: returns an error explanation.

Access mode: public.

4.11.1.1 Overview

This procedure returns a declared error explanation.

4.11.2 Command public API

Arguments:

Returns: the error explanation.

4.12 ::Simple::Error::information message errorCode

4.12.1 Command description

Synopsis: returns an error message format string.

Access mode: public.

4.12.1.1 Overview

This procedure returns a declared error message format string.

4.12.2 Command public API

Arguments:

Returns: the error message format string.

4.13 ::Simple::Error::throw ?-extra string? errorCode args

4.13.1 Command description

Synopsis: throws an error.

Access mode: public.

4.13.1.1 Overview

This procedure throws a declared error.

4.13.2 Command public API

Arguments:

Returns: none; the error is thrown.

Effects:

• The error is thrown.