Error reporting

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