Check , Assert , DumpErrors, ClearErrors , IsError , GetError, ClearError , CurrentFile, CurrentLine .

Error reporting

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

Check report "hard" errors
Assert signal "soft" custom error
DumpErrors, ClearErrors simple error handlers
IsError check for custom error
GetError, ClearError custom errors handlers
CurrentFile, CurrentLine show current file and line of input

Check -- report "hard" errors

Internal function
Calling format: 
Check(predicate,"error text")

Parameters:
predicate -- expression returning True or False

"error text" -- string to print on 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.

See also:
Assert .

Assert -- signal "soft" custom error

Standard library
Calling format: 
Assert("str", expr) pred
Assert("str") pred
Assert() pred
(bodied function, 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 the global variable ErrorTableau.

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

DumpErrors, 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, ClearError -- custom errors handlers

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

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.

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, CurrentLine -- show current file and line of 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 .