(directly go to documentation on : Check, TrapError, GetCoreError, Assert, DumpErrors, ClearErrors, IsError, GetError, ClearError, GetErrorTableau, CurrentFile, CurrentLine. )

4. Error reporting

This chapter contains commands useful for reporting errors to the user.

Check report "hard" errors
TrapError trap "hard" errors
GetCoreError get "hard" error string
Assert signal "soft" custom error
DumpErrors simple error handlers
ClearErrors simple error handlers
IsError check for custom error
GetError custom errors handlers
ClearError custom errors handlers
GetErrorTableau custom errors handlers
CurrentFile return current input file
CurrentLine return current line number on input


Check -- report "hard" errors


TrapError -- trap "hard" errors


GetCoreError -- get "hard" error string

Internal function
Calling format:
Check(predicate,"error text")
TrapError(expression,errorHandler)
GetCoreError()

Parameters:
predicate -- expression returning True or False

"error text" -- string to print on error

expression -- expression to evaluate (causing potential error)

errorHandler -- expression to be called to handle error

Description:
If predicate does not evaluate to True, the current operation will be stopped, the string "error text" will be printed, and control will be returned immediately to the command line. This facility can be used to assure that some condition is satisfied during evaluation of expressions (guarding against critical internal errors).

A "soft" error reporting facility that does not stop the execution is provided by the function Assert.

Example:
In> [Check(1=0,"bad value"); Echo(OK);]
In function "Check" : 
CommandLine(1) : "bad value"

Note that OK is not printed.

TrapError evaluates its argument expression, returning the result of evaluating expression. If an error occurs, errorHandler is evaluated, returning its return value in stead.

GetCoreError returns a string describing the core error. TrapError and GetCoreError can be used in combination to write a custom error handler.

See also:
Assert .


Assert -- signal "soft" custom error

Standard library
Calling format:
Assert("str", expr) pred
Assert("str") pred
Assert() pred
Precedence: 60000

Parameters:
pred -- predicate to check

"str" -- string to classify the error

expr -- expression, error object

Description:
Assert is a global error reporting mechanism. It can be used to check for errors and report them. An error is considered to occur when the predicate pred evaluates to anything except True. In this case, the function returns False and an error object is created and posted to the global error tableau. Otherwise the function returns True.

Unlike the "hard" error function Check, the function Assert does not stop the execution of the program.

The error object consists of the string "str" and an arbitrary expression expr. The string should be used to classify the kind of error that has occurred, for example "domain" or "format". The error object can be any expression that might be useful for handling the error later; for example, a list of erroneous values and explanations. The association list of error objects is currently obtainable through the function GetErrorTableau().

If the parameter expr is missing, Assert substitutes True. If both optional parameters "str" and expr are missing, Assert creates an error of class "generic".

Errors can be handled by a custom error handler in the portion of the code that is able to handle a certain class of errors. The functions IsError, GetError and ClearError can be used.

Normally, all errors posted to the error tableau during evaluation of an expression should be eventually printed to the screen. This is the behavior of prettyprinters DefaultPrint, Print, PrettyForm and TeXForm (but not of the inline prettyprinter, which is enabled by default); they call DumpErrors after evaluating the expression.

Examples:
In> Assert("bad value", "must be zero") 1=0
Out> False;
In> Assert("bad value", "must be one") 1=1
Out> True;
In> IsError()
Out> True;
In> IsError("bad value")
Out> True;
In> IsError("bad file")
Out> False;
In> GetError("bad value");
Out> "must be zero";
In> DumpErrors()
Error: bad value: must be zero
Out> True;
No more errors left:
In> IsError()
Out> False;
In> DumpErrors()
Out> True;

See also:
IsError , DumpErrors , Check , GetError , ClearError , ClearErrors , GetErrorTableau .


DumpErrors -- simple error handlers


ClearErrors -- simple error handlers

Standard library
Calling format:
DumpErrors()
ClearErrors()

Description:
DumpErrors is a simple error handler for the global error reporting mechanism. It prints all errors posted using Assert and clears the error tableau.

ClearErrors is a trivial error handler that does nothing except it clears the tableau.

See also:
Assert , IsError .


IsError -- check for custom error

Standard library
Calling format:
IsError()
IsError("str")

Parameters:
"str" -- string to classify the error

Description:
IsError() returns True if any custom errors have been reported using Assert. The second form takes a parameter "str" that designates the class of the error we are interested in. It returns True if any errors of the given class "str" have been reported.

See also:
GetError , ClearError , Assert , Check .


GetError -- custom errors handlers


ClearError -- custom errors handlers


GetErrorTableau -- custom errors handlers

Standard library
Calling format:
GetError("str")
ClearError("str")
GetErrorTableau()

Parameters:
"str" -- string to classify the error

Description:
These functions can be used to create a custom error handler.

GetError returns the error object if a custom error of class "str" has been reported using Assert, or False if no errors of this class have been reported.

ClearError("str") deletes the same error object that is returned by GetError("str"). It deletes at most one error object. It returns True if an object was found and deleted, and False otherwise.

GetErrorTableau() returns the entire association list of currently reported errors.

Examples:
In> x:=1
Out> 1;
In> Assert("bad value", {x,"must be zero"}) x=0
Out> False;
In> GetError("bad value")
Out> {1, "must be zero"};
In> ClearError("bad value");
Out> True;
In> IsError()
Out> False;

See also:
IsError , Assert , Check , ClearErrors .


CurrentFile -- return current input file


CurrentLine -- return current line number on input

Internal function
Calling format:
CurrentFile()
CurrentLine()

Description:
The functions CurrentFile and CurrentLine return a string with the file name of the current file and the current line of input respectively.

These functions are most useful in batch file calculations, where there is a need to determine at which line an error occurred. One can define a function

tst() := Echo({CurrentFile(),CurrentLine()});
which can then be inserted into the input file at various places, to see how far the interpreter reaches before an error occurs.

See also:
Echo .