6.11. kink/EXCEPTION

6.11.1. type exception

`exception` is an immutable tuple of (Message, Traces, optional Next) which represents a runtime error of program execution.

Message

`Message` is a `str` value of the error message.

Traces

`Traces` is a finite length sequence of `trace` values, in the order from the root to the top of the stack.

optional Next

An `exception` may or may not have another `exception` as `Next` attribute.

The sequence of `exception` values obtained by starting from `exception` `E` and following `Next` attributes is called a chain of exceptions. Here, `E` is called the main exception of the chain. A chain of exceptions is always finite length.

A chain of exceptions is constructed when there are more than one exceptions to report. For example, CONTROL.with_finally raises a chained exception when $body raises an exception, and cleanup thunks also raise exceptions.

Exceptions are for debugging

An `exception` contains information just for debugging of runtime errors. It does not contain hierarchical categories or error codes for programmatic error handling.

If you need to pass programmatic information to the caller, consider using continuation passing style instead. If you also need to abort processing down the stack, consider mixing continuation passing style and CONTROL.with_return.

6.11.1.1. Exception.message

`message` returns a `str` value which is equal to `Message` attribute.

6.11.1.2. Exception.traces

`traces` returns a `vec` which have `trace` values of `Traces` attribute.

6.11.1.3. Exception.have_next?

`have_next?` returns whether `Exception` has `Next` attribute.

6.11.1.4. Exception.next

`next` returns the `exception` of `Next` attribute.

Precondition

Exception.have_next? == true

6.11.1.5. Exception + Tail

`+` operator, or `op_add` method, concatenates the chain of `Exception` and the chain of `Tail`, and returns an `exception` of the new chain.

Precondition

`Tail` must be an `exception`.

6.11.1.6. Exception.raise

`raise` raises `Exception`.

At the tail of `raise`, the following sequence of abstract instructions is evaluated:

(val Exception)
(raise)

6.11.1.7. Exception.desc_iter

`desc_iter` returns an `iter` of `str` values which describe `Exception`.

The elements of the `iter` is expected to print by Printer.print_line method:

:CONTROL.require_from('kink/')

CONTROL.try(
  { 10 // 0 }
  { _not_reach_here_ }
  {(:Exc)
    Exc.desc_iter.each{(:Str)
      stderr.print_line('  ' + Str)
    }
  }
)
# Output:
#   -- main exception
#   [..root..]
#   ,,,
#   [builtin:kink-mods/kink/CONTROL.kn L101 C10 body] :R = -->body
#   {(stdin) L4 C8 op_intdiv} { 10 -->// 0 }
#   Num.op_intdiv(Divisor): zero division: 10 is divided by 0

6.11.1.8. E1 == E2

`==` operator, or `op_eq` method, returns whether the two exceptions have the equal attributes.

Precondition

`E2` must be an `exception`.

6.11.2. EXCEPTION.new(Message ...[Traces=TRACE.current_traces])

`new` returns a new `exception` with `Message` as `Message` attribute, `Traces` as `Traces` attribute, and without `Next` attribute.

Preconditions

`Message` must be a `str`.

`Traces` must be a `vec` of `trace` values.

6.11.3. EXCEPTION.is?(Val)

`is?` returns whether `Val` is an `exception`.