SimpleError v1.0 

 The Simple Development Library error handling 

Project: the Simple Development Library.

Table of contents

1. Package description
   1.1 Overview
   1.2 Usage
   1.3 Examples
   1.4 History
   1.5 Copyright
2. Package public API
   2.1 Types
      2.1.1 errorcode
   2.2 Options
   2.3 Namespaces
   2.4 Commands
      2.4.1 ::Simple::Error::catch-explain script ?variableName?
      2.4.2 ::Simple::Error::cget
      2.4.3 ::Simple::Error::configure
      2.4.4 ::Simple::Error::declare errorCode ?-message formatstring? ?-explanation string? ?-corrective string? ?-explained string? ?-translation string?
      2.4.5 ::Simple::Error::delete errorCode
      2.4.6 ::Simple::Error::explain errorCode
      2.4.7 ::Simple::Error::information corrective errorCode
      2.4.8 ::Simple::Error::information declared ?pattern?
      2.4.9 ::Simple::Error::information exists errorCode
      2.4.10 ::Simple::Error::information explained errorCode
      2.4.11 ::Simple::Error::information explanation errorCode
      2.4.12 ::Simple::Error::information message errorCode
      2.4.13 ::Simple::Error::throw ?-extra string? errorCode args
   2.5 Errors
      2.5.1 ::Simple::Error::FORMAT-ERROR
      2.5.2 ::Simple::Error::UNDECLARED-ERROR
3. Package further information
   3.1 Details
   3.2 Todo
4. Package command details
   4.1 ::Simple::Error::catch-explain script ?variableName?
      4.1.1 Command description
         4.1.1.1 Overview
      4.1.2 Command public API
   4.2 ::Simple::Error::cget
      4.2.1 Command description
      4.2.2 Command public API
   4.3 ::Simple::Error::configure
      4.3.1 Command description
      4.3.2 Command public API
   4.4 ::Simple::Error::declare errorCode ?-message formatstring? ?-explanation string? ?-corrective string? ?-explained string? ?-translation string?
      4.4.1 Command description
         4.4.1.1 Overview
      4.4.2 Command public API
      4.4.3 Command further information
         4.4.3.1 Remarks
   4.5 ::Simple::Error::delete errorCode
      4.5.1 Command description
      4.5.2 Command public API
   4.6 ::Simple::Error::explain errorCode
      4.6.1 Command description
         4.6.1.1 Overview
         4.6.1.2 Examples
      4.6.2 Command public API
   4.7 ::Simple::Error::information corrective errorCode
      4.7.1 Command description
         4.7.1.1 Overview
      4.7.2 Command public API
   4.8 ::Simple::Error::information declared ?pattern?
      4.8.1 Command description
         4.8.1.1 Overview
      4.8.2 Command public API
      4.8.3 Command further information
         4.8.3.1 Remarks
   4.9 ::Simple::Error::information exists errorCode
      4.9.1 Command description
      4.9.2 Command public API
   4.10 ::Simple::Error::information explained errorCode
      4.10.1 Command description
         4.10.1.1 Overview
      4.10.2 Command public API
   4.11 ::Simple::Error::information explanation errorCode
      4.11.1 Command description
         4.11.1.1 Overview
      4.11.2 Command public API
   4.12 ::Simple::Error::information message errorCode
      4.12.1 Command description
         4.12.1.1 Overview
      4.12.2 Command public API
   4.13 ::Simple::Error::throw ?-extra string? errorCode args
      4.13.1 Command description
         4.13.1.1 Overview
      4.13.2 Command public API

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

1.4 History

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

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

0 error message format string
1 error explanation
2 error corrective action
3 error explained error message
4 error translation string

3.2 Todo

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:

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:

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:

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.

4.4.3 Command further information

4.4.3.1 Remarks

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:

Argument Type Default value/ choices Description
errorCode errorcode (n/a) Error code

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

an appropriate error explanation would be

so that the error message included in this procedure return value would be

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

4.6.2 Command public API

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.

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:

Argument Type Default value/ choices Description
errorCode errorcode (n/a) Error code

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:

Argument Type Default value/ choices Description
?pattern? pattern (empty string) Pattern

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

4.8.3 Command further information

4.8.3.1 Remarks

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:

Argument Type Default value/ choices Description
errorCode errorcode (n/a) Error code

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:

Argument Type Default value/ choices Description
errorCode errorcode (n/a) Error code

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:

Argument Type Default value/ choices Description
errorCode errorcode (n/a) Error code

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:

Argument Type Default value/ choices Description
errorCode errorcode (n/a) Error code

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:

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: