# Module `errors`

Convenient error handling in Tarantool.

## Functions

is_error_object (obj) | Check if the argument is an error object.
new_class (class_name[, options]) | Create new error class.
netbox_eval (conn, code[, arguments[, options]]) | Do protected net.box evaluation.
netbox_call (conn, function_name[, arguments[, options]]) | Perform protected net.box call.
netbox_wait_async (future, timeout) | Wait for result from async net.box call / eval.
wrap ([...]) | Postprocess arguments.

## Functions (shortcuts)

new (class_name[, level], fmt[, ...]) | Shortcut for error_class:new.
pcall (class_name, fn[, ...]) | Shortcut for error_class:pcall.
assert (class_name, cond[, ...]) | Shortcut for error_class:assert.

## Class error_class

error_class:new ([level], fmt[, ...]) | Create error object.
error_class:pcall (fn[, ...]) | Perform protected Lua call, gathering error as object.
error_class:assert (cond[, ...]) | Raise an error object unless condition is true.

## Class error_object

error_object:tostring () | Get string representation.

## Tools for API deprecation

deprecate (message) | Issue deprecation error.
set_deprecation_handler (fn) | Set new deprecation handler.

## Functions

is_error_object (obj)
  Check if the argument is an error object.

  The check is positive if it's a table with mandatory fields: `err`, `str`, `line`, `file`, `class_name`. Their types aren't checked. Other fields are ignored.

  ### Parameters:

  - obj

  ### Returns:

  boolean true/false
new_class (class_name[, options])
  Create new error class.

  ### Parameters:

  - class_name string
  - options
    - capture_stack boolean Capture backtrace at creation. (default: true)
    - log_on_creation boolean Produce error log at creation. (default: false)

  ### Returns:

  error_class
netbox_eval (conn, code[, arguments[, options]])
  Do protected net.box evaluation. Execute code on remote server using Tarantool built-in `net.box` `conn:eval`. Additionally postprocess returned values with wrap.

  ### Parameters:

  - conn net.box connection object
  - code string
  - arguments passed to `net.box` `eval` (optional)
  - options passed to `net.box` `eval` (optional)

  ### Returns:

  Postprocessed `conn:eval()` result

  ### Or

  1. nil
  2. error_object Error description

  ### See also:

  netbox_call
netbox_call (conn, function_name[, arguments[, options]])
  Perform protected net.box call. Similar to netbox_eval, execute code on remote server using Tarantool built-in `net.box` `conn:call`. Additionally postprocess returned values with wrap.

  ### Parameters:

  - conn net.box connection object
  - function_name string
  - arguments passed to `net.box` `call` (optional)
  - options passed to `net.box` `call` (optional)

  ### Returns:

  Postprocessed `conn:call()` result

  ### Or

  1. nil
  2. error_object Error description

  ### See also:

  netbox_eval
netbox_wait_async (future, timeout)
  Wait for result from async net.box call / eval.

  Additionally postprocess returned values with wrap.

  ### Parameters:

  - future net.box future object
  - timeout number

  ### Returns:

  Postprocessed `future:wait_result()` result

  ### Or

  1. nil
  2. error_object Error description

  ### See also:

  - netbox_call
  - netbox_eval
wrap ([...])

  Postprocess arguments. Mostly useful for postprocessing net.box and vshard call results.

  - Substitute all `box.NULL` with `nil`;
  - Repair metatables of error objects because they are not transfered over network;
  - Extend stacktrace of remote call if possible;

  ### Parameters:

  - ... (optional)

  ### Returns:

  Postprocessed values

## Functions (shortcuts)

new (class_name[, level], fmt[, ...])

  Shortcut for error_class:new.

      errors.new_class(class_name):new(...)

  ### Parameters:

  - class_name string
  - level number (optional)
  - fmt string
  - ... (optional)
pcall (class_name, fn[, ...])

  Shortcut for error_class:pcall. Equivalent for

      errors.new_class(class_name):pcall(...)

  ### Parameters:

  - class_name string
  - fn function
  - ... (optional)
assert (class_name, cond[, ...])

  Shortcut for error_class:assert.

      errors.new_class(class_name):assert(...)

  ### Parameters:

  - class_name string
  - cond condition to be checked
  - ... `error_class:new` args (optional)

## Class error_class

error_class:new ([level], fmt[, ...])
  Create error object. Error payload is formatted by string.format

  ### Parameters:

  - level number within the meaning of Lua `debug.getinfo(level)` (optional)
  - fmt string used for `string.format(fmt, ...)`
  - ... formatting arguments (optional)

  ### Returns:

  error_object
error_class:pcall (fn[, ...])
  Perform protected Lua call, gathering error as object.

  ### Parameters:

  - fn function called function
  - ... call arguments (optional)

  ### Returns:

  `fn(...)` if the call succeeds without errors

  ### Or

  1. nil
  2. error_object
error_class:assert (cond[, ...])
  Raise an error object unless condition is true.

  ### Parameters:

  - cond condition to be checked
  - ... `error_class:new` args (optional)

  ### Returns:

  1. cond
  2. ...

  ### Raises:

  (error_object) `error_class:new(...)`

## Class error_object

A particular error object. Represented as a Lua table with the following fields:

- class_name: (string)
- err: (string)
- file: (string)
- line: (`number`)
- stack: (string)

error_object:tostring ()
  Get string representation. Including `class_name` and `err`. And optional `stack`, if it was not disabled for this class.

  ### Returns:

  string

## Tools for API deprecation

deprecate (message)
  Issue deprecation error. Do it once for every location in code, which points on the second-level caller.

  ### Parameters:

  - message string

  ### Returns:

  error_object
set_deprecation_handler (fn)
  Set new deprecation handler. It may be used in tests and development environment to turn warnings into noticable errors.

  By default (if handler is `nil`) all errors are logged using `log.warn()`.

  ### Parameters:

  - fn nil or functon

generated by LDoc 1.4.6 Last updated 2021-05-20 14:00:35