Exceptions

Library Design

The exception module belongs to the standard library: it is imported by default. It is written in Eve. A process that cannot continue raises an error; the workflow jumps into the recover region, where the developer reads $error. A warning does not interrupt the process: it is added to $trace and the process goes on. Warnings are reported in the final exit status of the driver.

Types

The class Error in the module Exception:

** system exception type
module exception is
  export (Error, raise, expect, assert, warn);

  ** an error: its class and its code identify it; the exit code of the process is separate
  class Error = {code: Integer, message: String, module: String, line: Integer, job: String} <: Object is
    constructor(code = 4, message = "" :String) => (@self) is
      let self := Object();
      let self.code := code;
      let self.message := message;
    return;
  end Error;

end exception;

System Variables and Objects

The other system variables are listed in System Variables.

Signatures

Only the signatures are given. A declaration with the keyword external keeps only the signature: it is implemented in Zig by the virtual machine. The source of the module is evevm/lib/exception.eve. An exception is an object {code: x, message: y}; raise is overloaded and accepts a constructor call, a code constant with a message, a code with a message, an exception object, or only a message (code 4).

** raise an exception object
external raise(e: Error);

** raise an error with a code and a message
external raise(code: Integer, message: String);

** raise an error with the default code 4
external raise(message: String);

** raise $err_expect when the condition is false
external expect(condition: Logic, message := "");

** raise $err_assert when the condition is false
external assert(condition: Logic, message := "");

** report a warning and go on
external warn(code: Integer, message: String);

Predefined Constants

Every standard error and warning has a predefined constant: $err_name for an exception and $wrn_name for a warning. The constant is the integer code. In the recover region you compare it with the code of the error:

recover
  if $error.code == $err_file do
    print "Skip the missing file: " / $error.message;
    resume;
  else
    abort;
  done;

The constants are read only. An error is not an exit code: a driver that ends with an unhandled error ends with the exit code 4, and reports the code and the message of the error (see Exit Codes).

Error Classes

Every standard error is an object of a class derived from Error, and every class has its code (table Standard Exceptions). In the recover region you can test the class with is and read its fields, or compare the code with a constant:

recover
  if $error is IoError do
    retry;                          ** a transient error: try the job again
  else if $error.code == $err_file do
    resume;                         ** a missing file: go on
  else
    abort;
  done;

A project defines its own errors as classes derived from Error, with codes from the project range: class HttpError = {status: Integer} <: Error;.

Code Ranges

Standard Exceptions

A message pattern is the message of the error. A name in braces is replaced with the value that caused the error. When a new exception is needed, add it to this table with the next free code of its range, then use its constant.

Standard Warnings

The same rule applies: list every new warning in this table.

Exit Codes

The exit code of a process is a small number. It tells a shell or a scheduler how the process ended; the error itself is in the message.

Read next: Databases