Expand DML API with tuple-based functions

This patch completes series of patches that allow to use raw
tuples as input and output arguments.
It was decided to use insert/replace/delete functions only for raw
tuples. In contrast {insert/replace/delete}_object functions
allow to put unflattened objects as it was before.

Closes #6

Author: olegrok

README.md

@@ -21,25 +21,25 @@ across the cluster.
 ### Insert
 
 ```lua
-local object, err = crud.insert(space_name, object, opts)
+-- Insert tuple
+local result, err = crud.insert(space_name, tuple, opts)
+-- Insert object
+local result, err = crud.insert_object(space_name, object, opts)
 ```
 
 where:
 
 * `space_name` (`string`) - name of the space to insert an object
-* `object` (`table`) - object to insert
+* `tuple` / `object` (`table`) - tuple/object to insert
 * `opts`:
   * `timeout` (`?number`) - `vshard.call` timeout (in seconds)
 
-Returns inserted object, error.
+Returns inserted rows and metadata or nil with error.
 
 **Example:**
 
 ```lua
-crud.insert('customers', {
-    id = 1, name = 'Elizabeth', age = 23,
-})
----
+crud.insert('customers', {1, box.NULL, 'Elizabeth', 23})
 ---
 - metadata:
   - {'name': 'id', 'type': 'unsigned'}
@@ -49,6 +49,18 @@ crud.insert('customers', {
   rows:
   - [1, 477, 'Elizabeth', 23]
 ...
+crud.insert_object('customers', {
+    id = 2, name = 'Elizabeth', age = 24,
+})
+---
+- metadata:
+  - {'name': 'id', 'type': 'unsigned'}
+  - {'name': 'bucket_id', 'type': 'unsigned'}
+  - {'name': 'name', 'type': 'string'}
+  - {'name': 'age', 'type': 'number'}
+  rows:
+  - [2, 401, 'Elizabeth', 24]
+...
 ```
 
 ### Get
@@ -144,22 +156,35 @@ crud.delete('customers', 1)
 ### Replace
 
 ```lua
-local object, err = crud.replace(space_name, object, opts)
+-- Replace tuple
+local result, err = crud.replace(space_name, tuple, opts)
+-- Replace object
+local result, err = crud.replace_object(space_name, object, opts)
 ```
 
 where:
 
 * `space_name` (`string`) - name of the space
-* `object` (`table`) - object to insert or replace exist one
+* `tuple` / `object` (`table`) - tuple/object to insert or replace exist one
 * `opts`:
   * `timeout` (`?number`) - `vshard.call` timeout (in seconds)
 
-Returns inserted or replaced object, error.
+Returns inserted or replaced rows and metadata or nil with error.
 
 **Example:**
 
 ```lua
-crud.replace('customers', {
+crud.replace('customers', {1, box.NULL, 'Alice', 22})
+---
+- metadata:
+  - {'name': 'id', 'type': 'unsigned'}
+  - {'name': 'bucket_id', 'type': 'unsigned'}
+  - {'name': 'name', 'type': 'string'}
+  - {'name': 'age', 'type': 'number'}
+  rows:
+  - [1, 477, 'Alice', 22]
+...
+crud.replace_object('customers', {
     id = 1, name = 'Alice', age = 22,
 })
 ---
@@ -176,24 +201,38 @@ crud.replace('customers', {
 ### Upsert
 
 ```lua
-local object, err = crud.upsert(space_name, object, operations, opts)
+-- Upsert tuple
+local result, err = crud.upsert(space_name, tuple, operations, opts)
+-- Upsert object
+local result, err = crud.upsert_object(space_name, tuple, operations, opts)
 ```
 
 where:
 
 * `space_name` (`string`) - name of the space
-* `object` (`table`) - object to insert if there is no existing tuple which matches the key fields
+* `tuple` / `object` (`table`) - tuple/object to insert if there is no existing tuple which matches the key fields
 * `operations` (`table`) - update [operations](https://www.tarantool.io/en/doc/latest/reference/reference_lua/box_space/#box-space-update) if there is an existing tuple which matches the key fields of tuple
 * `opts`:
   * `timeout` (`?number`) - `vshard.call` timeout (in seconds)
 
-Returns nil, error.
+Returns metadata and empty array of rows or nil, error.
 
 **Example:**
 
 ```lua
 crud.upsert('customers',
-    {id = 1, name = 'Alice', age = 22,},
+    {1, box.NULL, 'Alice', 22},
+    {{'+', 'age', 1}})
+---
+- metadata:
+  - {'name': 'id', 'type': 'unsigned'}
+  - {'name': 'bucket_id', 'type': 'unsigned'}
+  - {'name': 'name', 'type': 'string'}
+  - {'name': 'age', 'type': 'number'}
+  rows: []
+...
+crud.upsert_object('customers',
+    {id = 1, name = 'Alice', age = 22},
     {{'+', 'age', 1}})
 ---
 - metadata:

crud.lua

@@ -25,25 +25,37 @@ crud.register = registry.add
 --- CRUD operations.
 -- @section crud
 
--- @refer insert.object
+-- @refer insert.tuple
 -- @function insert
-crud.insert = insert.object
+crud.insert = insert.tuple
+
+-- @refer insert.object
+-- @function insert_object
+crud.insert_object = insert.object
 
 -- @refer get.call
 -- @function get
 crud.get = get.call
 
--- @refer replace.object
+-- @refer replace.tuple
 -- @function replace
-crud.replace = replace.object
+crud.replace = replace.tuple
+
+-- @refer replace.object
+-- @function replace_object
+crud.replace_object = replace.object
 
 -- @refer update.call
 -- @function update
 crud.update = update.call
 
+-- @refer upsert.tuple
+-- @function upsert
+crud.upsert = upsert.tuple
+
 -- @refer upsert.object
 -- @function upsert
-crud.upsert = upsert.object
+crud.upsert_object = upsert.object
 
 -- @refer delete.call
 -- @function delete

crud/insert.lua

@@ -120,7 +120,7 @@ function insert.object(space_name, obj, opts)
 
     local space = utils.get_space(space_name, vshard.router.routeall())
     if space == nil then
-        return nil, InsertError:new("Space %q doesn't exists", space_name)
+        return nil, InsertError:new("Space %q doesn't exist", space_name)
     end
     local space_format = space:format()
 

crud/replace.lua

@@ -120,7 +120,7 @@ function replace.object(space_name, obj, opts)
 
     local space = utils.get_space(space_name, vshard.router.routeall())
     if space == nil then
-        return nil, ReplaceError:new("Space %q doesn't exists", space_name)
+        return nil, ReplaceError:new("Space %q doesn't exist", space_name)
     end
 
     local space_format = space:format()

crud/upsert.lua

@@ -134,7 +134,7 @@ function upsert.object(space_name, obj, user_operations, opts)
 
     local space = utils.get_space(space_name, vshard.router.routeall())
     if space == nil then
-        return nil, UpsertError:new("Space %q doesn't exists", space_name)
+        return nil, UpsertError:new("Space %q doesn't exist", space_name)
     end
 
     local space_format = space:format()

test/integration/pairs_test.lua

@@ -86,7 +86,7 @@ local function insert_customers(g, customers)
     for _, customer in ipairs(customers) do
         local result, err = g.cluster.main_server.net_box:eval([[
             local crud = require('crud')
-            return crud.insert('customers', ...)
+            return crud.insert_object('customers', ...)
         ]],{customer})
 
         t.assert_equals(err, nil)

test/integration/select_test.lua

@@ -81,7 +81,7 @@ local function insert_customers(g, customers)
     for _, customer in ipairs(customers) do
         local result, err = g.cluster.main_server.net_box:eval([[
             local crud = require('crud')
-            return crud.insert('customers', ...)
+            return crud.insert_object('customers', ...)
         ]],{customer})
 
         t.assert_equals(err, nil)