Add varbinary docs (#4405)

Resolves #3551

Co-authored-by: Andrey Aksenov <38073144+andreyaksenov@users.noreply.github.com>

Author: p7nov

doc/code_snippets/test/varbinary/varbinary_test.lua

@@ -0,0 +1,37 @@
+local varbinary = require('varbinary')
+
+-- Create a varbinary object
+local bin = varbinary.new('data')
+local bin_hex = varbinary.new('\xFF\xFE')
+
+-- Check whether a value is a varbinary object
+varbinary.is(bin) -- true
+varbinary.is(bin_hex) -- true
+varbinary.is(100) -- false
+varbinary.is('data') -- false
+
+-- Check varbinary objects equality
+print(bin == varbinary.new('data')) -- true
+print(bin == 'data') -- true
+print(bin ~= 'data1') -- true
+print(bin_hex ~= '\xFF\xFE') -- false
+
+-- Check varbinary objects length
+print(#bin) -- 4
+print(#bin_hex) -- 2
+
+-- Print string representation
+print(tostring(bin)) -- data
+
+local bin2 = varbinary.new(ffi.cast('const char *', 'data'), 4)
+varbinary.is(bin2) -- true
+print(bin2) -- data
+
+local luatest = require('luatest')
+local test_group = luatest.group()
+test_group.test_varbinary = function()
+    luatest.assert_equals(varbinary.is(bin), true)
+    luatest.assert_equals(bin, 'data')
+    luatest.assert_equals(#bin, 4)
+    luatest.assert_equals(#varbinary.new('\xFF\xFE'), 2)
+end

doc/platform/app/cookbook.rst

@@ -249,56 +249,6 @@ a metatable).
     local b = a + point(0.5, 8)
     print(#b)        --> 12.5
 
-.. _cookbook-ffi_varbinary_insert:
-
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-ffi_varbinary_insert.lua
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-Use the `LuaJIT ffi library <http://luajit.org/ext_ffi.html>`_ to
-insert a tuple which has a VARBINARY field.
-
-Note that it is allowed only inside a memtx transaction: when ``box_insert()``
-does not yield.
-
-Lua does not have direct support for VARBINARY, so using C
-is one way to put in data which in MessagePack is stored as bin
-(MP_BIN). If the tuple is retrieved later, field "b" will have type = 'cdata'.
-
-.. code-block:: lua
-
-    #!/usr/bin/env tarantool
-
-    -- box.cfg{} should be here
-
-    s = box.schema.space.create('withdata')
-    s:format({{"b", "varbinary"}})
-    s:create_index('pk', {parts = {1, "varbinary"}})
-
-    buffer = require('buffer')
-    ffi = require('ffi')
-
-    function varbinary_insert(space, bytes)
-        local tmpbuf = buffer.ibuf()
-        local p = tmpbuf:alloc(3 + #bytes)
-        p[0] = 0x91 -- MsgPack code for "array-1"
-        p[1] = 0xC4 -- MsgPack code for "bin-8" so up to 256 bytes
-        p[2] = #bytes
-        for i, c in pairs(bytes) do p[i + 3 - 1] = c end
-        ffi.cdef[[int box_insert(uint32_t space_id,
-                                 const char *tuple,
-                                 const char *tuple_end,
-                                 box_tuple_t **result);]]
-        ffi.C.box_insert(space.id, tmpbuf.rpos, tmpbuf.wpos, nil)
-        tmpbuf:recycle()
-    end
-
-    varbinary_insert(s, {0xDE, 0xAD, 0xBE, 0xAF})
-    varbinary_insert(s, {0xFE, 0xED, 0xFA, 0xCE})
-
-    -- if successful, Tarantool enters the event loop now
-
-
 .. _cookbook-print_arrays:
 
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

doc/platform/ddl_dml/value_store.rst

@@ -345,9 +345,8 @@ bin
 ***
 
 A bin (binary) value is not directly supported by Lua but there is
-a Tarantool type ``varbinary`` which is encoded as MsgPack binary.
-For an (advanced) example showing how to insert varbinary into a database,
-see the Cookbook Recipe for :ref:`ffi_varbinary_insert <cookbook-ffi_varbinary_insert>`.
+a Tarantool type ``varbinary``. See the :ref:`varbinary module reference <varbinary-module>`
+for details.
 
 **Example:** ``"\65 \66 \67"``.
 

doc/reference/configuration/configuration_reference.rst

@@ -431,6 +431,8 @@ The ``compat`` section defines values of the :ref:`compat <compat-module>` modul
     -   ``new``: as varbinary objects
     -   ``old``: as plain strings
 
+    See also: :ref:`compat-option-binary-decoding`
+
     |
     | Type: string
     | Possible values: 'new', 'old'

doc/reference/reference_lua/compat.rst

@@ -72,6 +72,7 @@ Below are the available ``compat`` options:
 * :doc:`box_cfg_replication_sync_timeout <./compat/box_cfg_replication_sync_timeout>`
 * :doc:`sql_seq_scan_default <./compat/sql_seq_scan_default>`
 * :doc:`fiber_slice_default <./compat/fiber_slice_default>`
+* :doc:`binary_data_decoding <./compat/binary_data_decoding>`
 
 ..  toctree::
     :hidden:
@@ -82,4 +83,5 @@ Below are the available ``compat`` options:
     compat/box_cfg_replication_sync_timeout
     compat/sql_seq_scan_default
     compat/fiber_slice_default
+    compat/binary_data_decoding
     compat/compat_tutorial

doc/reference/reference_lua/compat/binary_data_decoding.rst

@@ -0,0 +1,59 @@
+.. _compat-option-binary-decoding:
+
+Decoding binary objects
+=======================
+
+Option: ``binary_data_decoding``
+
+Starting from version 3.0, Tarantool has the :ref:`varbinary <varbinary-module>` module
+for handling binary objects of arbitrary lengths.
+The ``binary_data_decoding`` compat option allows to define the format in which
+varbinary field values are returned for handling in Lua: plain strings or ``varbinary``
+objects.
+
+Old and new behavior
+--------------------
+
+New behavior: ``varbinary`` field values are returned as ``varbinary`` objects.
+
+..  code-block:: tarantoolsession
+
+    tarantool> compat.binary_data_decoding = 'new'
+    ---
+    ...
+
+    tarantool> varbinary.is(msgpack.decode('\xC4\x02\xFF\xFE'))
+    ---
+    - true
+    ...
+
+Old behavior: ``varbinary`` field values are returned as plain strings.
+
+..  code-block:: tarantoolsession
+
+    tarantool> compat.binary_data_decoding = 'old'
+    ---
+    ...
+
+    tarantool> varbinary.is(msgpack.decode('\xC4\x02\xFF\xFE'))
+    ---
+    - false
+    ...
+
+    tarantool> varbinary.is(yaml.decode('!!binary //4='))
+    ---
+    - false
+    ...
+
+Known compatibility issues
+--------------------------
+
+At this point, no incompatible modules are known.
+
+Detecting issues in your codebase
+---------------------------------
+
+String manipulation methods, such as ``string.sub()`` or ``string.match()`` are not
+defined for ``varbinary`` objects. Thus, if you use such methods on results of
+binary data decoding from MsgPack or YAML, convert them to strings
+explicitly using the ``tostring()`` method.

doc/reference/reference_lua/index.rst

@@ -58,9 +58,10 @@ This reference covers Tarantool's built-in Lua modules.
     table
     tap
     tarantool
-    uuid
-    utf8
     uri
+    utf8
+    uuid
+    varbinary
     xlog
     yaml
     other