Update docs for errors

doc/code_snippets/test/errors/error_list_test.lua

@@ -0,0 +1,47 @@
+local status, err = pcall(function()
+    -- snippet_start
+    local base_server_error = box.error.new({ code = 500,
+                                              reason = 'Base server error',
+                                              type = 'BaseServerError' })
+    local storage_server_error = box.error.new({ code = 507,
+                                                 reason = 'Not enough storage',
+                                                 type = 'StorageServerError' })
+
+    base_server_error:set_prev(storage_server_error)
+    --[[
+    ---
+    ...
+    --]]
+
+    box.error(base_server_error)
+    --[[
+    ---
+    - error: Base server error
+    ...
+    --]]
+
+    box.error.last().prev:unpack()
+    --[[
+    ---
+    - code: 507
+      base_type: CustomError
+      type: StorageServerError
+      custom_type: StorageServerError
+      message: Not enough storage
+      trace:
+      - file: '[string "storage_server_error = box.error.new({ code =..."]'
+        line: 1
+    ...
+    --]]
+    -- snippet_end
+end)
+
+-- Tests
+local luatest = require('luatest')
+local test_group = luatest.group()
+test_group.test_error_is_raised = function()
+    luatest.assert_equals(err:unpack().type, 'BaseServerError')
+    luatest.assert_equals(err:unpack().message, 'Base server error')
+    luatest.assert_equals(err.prev:unpack().type, 'StorageServerError')
+    luatest.assert_equals(err.prev:unpack().message, 'Not enough storage')
+end

doc/code_snippets/test/errors/raise_error_array_custom_type_args_test.lua

@@ -0,0 +1,18 @@
+local status, err = pcall(function()
+    -- snippet_start
+    box.error('CustomConnectionError', '%s cannot connect to the port %u', 'client', 8080)
+    --[[
+    ---
+    - error: client cannot connect to the port 8080
+    ...
+    --]]
+    -- snippet_end
+end)
+
+-- Tests
+local luatest = require('luatest')
+local test_group = luatest.group()
+test_group.test_error_is_raised = function()
+    luatest.assert_equals(err:unpack().type, 'CustomConnectionError')
+    luatest.assert_equals(err:unpack().message, 'client cannot connect to the port 8080')
+end

doc/code_snippets/test/errors/raise_error_array_custom_type_test.lua

@@ -0,0 +1,18 @@
+local status, err = pcall(function()
+    -- snippet_start
+    box.error('CustomConnectionError', 'cannot connect to the given port')
+    --[[
+    ---
+    - error: cannot connect to the given port
+    ...
+    --]]
+    -- snippet_end
+end)
+
+-- Tests
+local luatest = require('luatest')
+local test_group = luatest.group()
+test_group.test_error_is_raised = function()
+    luatest.assert_equals(err:unpack().type, 'CustomConnectionError')
+    luatest.assert_equals(err:unpack().message, 'cannot connect to the given port')
+end

doc/code_snippets/test/errors/raise_error_table_custom_type_test.lua

@@ -0,0 +1,20 @@
+local status, err = pcall(function()
+    -- snippet_start
+    box.error { code = 500,
+                reason = 'Internal server error',
+                type = 'CustomInternalError' }
+    --[[
+    ---
+    - error: Internal server error
+    ...
+    --]]
+    -- snippet_end
+end)
+
+-- Tests
+local luatest = require('luatest')
+local test_group = luatest.group()
+test_group.test_error_is_raised = function()
+    luatest.assert_equals(err:unpack().type, 'CustomInternalError')
+    luatest.assert_equals(err:unpack().message, 'Internal server error')
+end

doc/code_snippets/test/errors/raise_error_table_test.lua

@@ -0,0 +1,18 @@
+local status, err = pcall(function()
+    -- snippet_start
+    box.error { code = 500,
+                reason = 'Custom server error' }
+    --[[
+    ---
+    - error: Custom server error
+    ...
+    --]]
+    -- snippet_end
+end)
+
+-- Tests
+local luatest = require('luatest')
+local test_group = luatest.group()
+test_group.test_error_is_raised = function()
+    luatest.assert_equals(err:unpack().message, 'Custom server error')
+end

doc/code_snippets/test/errors/raise_new_error_array_custom_type_test.lua

@@ -0,0 +1,20 @@
+local status, err = pcall(function()
+    -- snippet_start
+    local custom_error = box.error.new('CustomInternalError', 'Internal server error')
+
+    box.error(custom_error)
+    --[[
+    ---
+    - error: Internal server error
+    ...
+    --]]
+    -- snippet_end
+end)
+
+-- Tests
+local luatest = require('luatest')
+local test_group = luatest.group()
+test_group.test_error_is_raised = function()
+    luatest.assert_equals(err:unpack().type, 'CustomInternalError')
+    luatest.assert_equals(err:unpack().message, 'Internal server error')
+end

doc/code_snippets/test/errors/raise_new_error_table_custom_type_test.lua

@@ -0,0 +1,22 @@
+local status, err = pcall(function()
+    -- snippet_start
+    local custom_error = box.error.new({ code = 500,
+                                         reason = 'Internal server error',
+                                         type = 'CustomInternalError' })
+
+    box.error(custom_error)
+    --[[
+    ---
+    - error: Internal server error
+    ...
+    --]]
+    -- snippet_end
+end)
+
+-- Tests
+local luatest = require('luatest')
+local test_group = luatest.group()
+test_group.test_error_is_raised = function()
+    luatest.assert_equals(err:unpack().type, 'CustomInternalError')
+    luatest.assert_equals(err:unpack().message, 'Internal server error')
+end

doc/code_snippets/test/errors/raise_new_error_table_test.lua

@@ -0,0 +1,21 @@
+local status, err = pcall(function()
+    -- snippet_start
+    local custom_error = box.error.new({ code = 500,
+                                         reason = 'Internal server error' })
+
+    box.error(custom_error)
+    --[[
+    ---
+    - error: Internal server error
+    ...
+    --]]
+    -- snippet_end
+end)
+
+-- Tests
+local luatest = require('luatest')
+local test_group = luatest.group()
+test_group.test_error_is_raised = function()
+    luatest.assert_equals(err:unpack().type, 'ClientError')
+    luatest.assert_equals(err:unpack().message, 'Internal server error')
+end

doc/code_snippets/test/errors/raise_new_tarantool_error_multiple_arg_test.lua

@@ -0,0 +1,19 @@
+local status, err = pcall(function()
+    -- snippet_start
+    local custom_error = box.error.new(box.error.CREATE_SPACE, 'my_space', 'the space already exists')
+
+    box.error(custom_error)
+    --[[
+    ---
+    - error: 'Failed to create space ''my_space'': the space already exists'
+    ...
+    --]]
+    -- snippet_end
+end)
+
+-- Tests
+local luatest = require('luatest')
+local test_group = luatest.group()
+test_group.test_tarantool_error_is_raised = function()
+    luatest.assert_equals(err:unpack().message, "Failed to create space 'my_space': the space already exists")
+end

doc/code_snippets/test/errors/raise_new_tarantool_error_one_arg_test.lua

@@ -0,0 +1,19 @@
+local status, err = pcall(function()
+    -- snippet_start
+    local custom_error = box.error.new(box.error.NO_SUCH_USER, 'John')
+
+    box.error(custom_error)
+    --[[
+    ---
+    - error: User 'John' is not found
+    ...
+    --]]
+    -- snippet_end
+end)
+
+-- Tests
+local luatest = require('luatest')
+local test_group = luatest.group()
+test_group.test_tarantool_error_is_raised = function()
+    luatest.assert_equals(err:unpack().message, "User 'John' is not found")
+end

doc/code_snippets/test/errors/raise_tarantool_error_multiple_arg_test.lua

@@ -0,0 +1,17 @@
+local status, err = pcall(function()
+    -- snippet_start
+    box.error(box.error.CREATE_SPACE, 'my_space', 'the space already exists')
+    --[[
+    ---
+    - error: 'Failed to create space ''my_space'': the space already exists'
+    ...
+    --]]
+    -- snippet_end
+end)
+
+-- Tests
+local luatest = require('luatest')
+local test_group = luatest.group()
+test_group.test_tarantool_error_is_raised = function()
+    luatest.assert_equals(err:unpack().message, "Failed to create space 'my_space': the space already exists")
+end

doc/code_snippets/test/errors/raise_tarantool_error_no_arg_test.lua

@@ -0,0 +1,17 @@
+local status, err = pcall(function()
+    -- snippet_start
+    box.error(box.error.READONLY)
+    --[[
+    ---
+    - error: Can't modify data on a read-only instance
+    ...
+    --]]
+    -- snippet_end
+end)
+
+-- Tests
+local luatest = require('luatest')
+local test_group = luatest.group()
+test_group.test_tarantool_error_is_raised = function()
+    luatest.assert_equals(err:unpack().message, "Can't modify data on a read-only instance")
+end

doc/code_snippets/test/errors/raise_tarantool_error_one_arg_test.lua

@@ -0,0 +1,17 @@
+local status, err = pcall(function()
+    -- snippet_start
+    box.error(box.error.NO_SUCH_USER, 'John')
+    --[[
+    ---
+    - error: User 'John' is not found
+    ...
+    --]]
+    -- snippet_end
+end)
+
+-- Tests
+local luatest = require('luatest')
+local test_group = luatest.group()
+test_group.test_tarantool_error_is_raised = function()
+    luatest.assert_equals(err:unpack().message, "User 'John' is not found")
+end

doc/code_snippets/test/errors/set_error_test.lua

@@ -0,0 +1,45 @@
+local status, err = pcall(function()
+    -- snippet_start
+    -- Create two errors --
+    local error1 = box.error.new({ code = 500, reason = 'Custom error 1' })
+    local error2 = box.error.new({ code = 505, reason = 'Custom error 2' })
+
+    -- Raise the first error --
+    box.error(error1)
+    --[[
+    ---
+    - error: Custom error 1
+    ...
+    --]]
+
+    -- Get the last error --
+    box.error.last()
+    --[[
+    ---
+    - Custom error 1
+    ...
+    --]]
+
+    -- Set the second error as the last error --
+    box.error.set(error2)
+    --[[
+    ---
+    ...
+    --]]
+
+    -- Get the last error --
+    box.error.last()
+    --[[
+    ---
+    - Custom error 2
+    ...
+    --]]
+    -- snippet_end
+end)
+
+-- Tests
+local luatest = require('luatest')
+local test_group = luatest.group()
+test_group.test_error_is_raised = function()
+    luatest.assert_equals(err:unpack().message, 'Custom error 1')
+end

doc/code_snippets/test/errors/unpack_clear_error_test.lua

@@ -0,0 +1,63 @@
+local status, err = pcall(function()
+    -- Create an error: start
+    local custom_error = box.error.new({ code = 500,
+                                         reason = 'Internal server error',
+                                         type = 'CustomInternalError' })
+    -- Create an error: end
+
+    -- Raise the error: start
+    box.error(custom_error)
+    --[[
+    ---
+    - error: Internal server error
+    ...
+    --]]
+    -- Raise the error: end
+
+    -- Get the last error: start
+    box.error.last()
+    --[[
+    ---
+    - error: Internal server error
+    ...
+    --]]
+    -- Get the last error: end
+
+    -- Get error details: start
+    box.error.last():unpack()
+    --[[
+    ---
+    - code: 500
+      base_type: CustomError
+      type: CustomInternalError
+      custom_type: CustomInternalError
+      message: Internal server error
+      trace:
+      - file: '[string "custom_error = box.error.new({ code = 500,..."]'
+        line: 1
+    ...
+    --]]
+    -- Get error details: end
+
+    -- Clear the errors: start
+    box.error.clear()
+    --[[
+    ---
+    ...
+    --]]
+    box.error.last()
+    --[[
+    ---
+    - null
+    ...
+    --]]
+    -- Clear the errors: end
+end)
+
+-- Tests
+local luatest = require('luatest')
+local test_group = luatest.group()
+test_group.test_error_is_raised = function()
+    luatest.assert_equals(err:unpack().type, 'CustomInternalError')
+    luatest.assert_equals(err:unpack().message, 'Internal server error')
+end