Document `level` argument of `box.error` and `box.error.new`

[TarantoolBot]

Related dev. issue(s): tarantool/tarantool#9792

Product: Tarantool
Since: 3.1
Root document:

• https://www.tarantool.io/en/doc/latest/reference/reference_lua/box_error/error/
• https://www.tarantool.io/en/doc/latest/reference/reference_lua/box_error/new/

SME: @ locker

Details

Now, when used with a table argument, box.error and box.error.new
also accept an optional second argument called level. It has the same
meaning as the level argument of the built-in Lua function error:
it specifies how to get the error location. With level 1 (the default),
the error location is where box.error / box.error.new was called.
Level 2 points the error to where the function that called box.error /
box.error.new was called; and so on. Passing level 0 avoids addition
of location information to the error.

Example of using level with box.error:

local json = require('json')

local function inner(level)
    box.error({message = 'test'}, level)    -- line:4
end

local function outer(level)
    inner(level)                            -- line:8
end

local ok, err
ok, err = pcall(outer)
print(json.encode(err.trace))               -- prints line:4
ok, err = pcall(outer, 1)
print(json.encode(err.trace))               -- prints line:4
ok, err = pcall(outer, 2)
print(json.encode(err.trace))               -- prints line:8
ok, err = pcall(outer, 0)
print(json.encode(err.trace))               -- prints empty table

Example of using level with box.error.new:

local json = require('json')

local function inner(level)
    local err = box.error.new({message = 'test'}, level)    -- line:4
    return err
end

local function outer(level)
    local err = inner(level)                                -- line:9
    return err
end

local err
err = outer()
print(json.encode(err.trace))               -- prints line:4
err = outer(1)
print(json.encode(err.trace))               -- prints line:4
err = outer(2)
print(json.encode(err.trace))               -- prints line:9
ok, err = pcall(outer, 0)
print(json.encode(err.trace))               -- prints empty table

It is also possible to specify level when using box.error to
re-raise an error created earlier with box.error.new, for example:

local json = require('json')

local err0 = box.error.new{message = 'test'}    -- line:3

local function raise(err, level)
    box.error(err, level)                       -- line:6
end

ok, err = pcall(raise, err0)
print(json.encode(err.trace))               -- prints line:3

ok, err = pcall(raise, err0, 1)
print(json.encode(err.trace))               -- prints line:6

ok, err = pcall(raise, err0, 0)
print(json.encode(err.trace))               -- prints empty table

Requested by @ locker in tarantool/tarantool@25cdabe.