Formats for standalone tuples and `box_tuple_new_vararg` compat opt

Related dev. issue(s): GitHub link(s)

Product: Tarantool
Since: 3.0
Root document: https://www.tarantool.io/en/doc/latest/reference/reference_lua/box_tuple/
SME: @ CuriousGeorgiy

Details

A new box.tuple.format library was added, with a tuple format constructor
(new) and a tuple format validator (is).

New tuple format objects (userdata) were added, which can be used with the
same format clause as for the space:format method (except that check
constraints and foreign keys are disabled for them):
NO_WRAP

f = box.tuple.format.new(box.space._space:format())
f = box.tuple.format.new{{name = 'field1', type = 'string', is_nullable = true,
                          nullable_action = 'none', collation = 'unicode_uk_s2',
                          default = 'UPPER("string")',
                          constraint = {ck = 'box.schema.user.info'},
                          foreign_key = {fk = {space = '_space', field = 'name'}}},
                          {name = 'field2', nullable_action = 'ignore',
                          foreign_key = {fk = {space = '_space', field = 1}}}}

NO_WRAP

Format objects have several introspection methods: :pairs, :ipairs,
totable, and also have a __serialize metamethod — these methods return
the original (i.e., user-provided) format clause. :pairs is an alias to
ipairs (since the format clause is an array by nature), and the totable
method is an alias to the __serialize metamethod, which returns an array
of field definitions.

Format objects also have a :tostring method, which simply returns a
"box.tuple.format" literal.

The standalone tuple constructor, box.tuple.new was extended with an
options parameter which currently has one available option, format
(default value is nil, i.e., no format). The format option is either a
tuple format object previously created using box.tuple.format.new or a
format clause.

Examples of standalone tuple creation with formats:
NO_WRAP

box.tuple.new({1}, {format = {{name = 'field', type = 'number'}}})
box.tuple.new({1}, {format = {{'field', type = 'number'}}})
box.tuple.new({1}, {format = {{'field', 'number'}}})

f = box.tuple.format.new({{name = 'field', type = 'number'}})
box.tuple.new({}, {format = f})
box.tuple.new({1}, {format = f})
box.tuple.new({'str'}, {format = f})
-- error: Tuple field 1 (field) type does not match one required by operation: expected number, got string
box.tuple.new({'str'}, {format = f})

NO_WRAP

See also the design document https://www.notion.so/tarantool/Schemafull-IPROTO-cc315ad6bdd641dea66ad854992d8cbf?pvs=4#a33e2d7418d249679969e5f21ef2832c

A new box_tuple_new_vararg compatibility option was introduced: a new
page needs to be created for it (https://tarantool.io/compat/box_tuple_new_vararg)

This option controls whether box.tuple.new should interpret an argument
list as an array of tuple fields (i.e., vararg, old behaviour), or as a
value plus a tuple format (new default behaviour). The value can be either
a scalar, an array or a box tuple. The old behaviour does not allow
creating formatted standalone tuples.

Old behaviour examples:

box.tuple.new(1)
box.tuple.new{1}
box.tuple.new(1, 2, 3)
box.tuple.new{1, 2, 3}
-- This won't create a formatted tuple: the format option will become the
-- second tuple field.
box.tuple.new({1, 2, 3}, {format = box.tuple.format.new{{'field'}}})

New behaviour examples:

box.tuple.new(1)
box.tuple.new(1, {format = box.tuple.format.new{{'field'}}})
box.tuple.new{1}
box.tuple.new({1}, {format = box.tuple.format.new{{'field'}}})
box.tuple.new(1, 2, 3) -- error
box.tuple.new(1, 2, 3, {format = box.tuple.format.new{{'field'}}}) -- error
box.tuple.new{1, 2, 3}
box.tuple.new({1, 2, 3}, {format = box.tuple.format.new{{'field'}}})

See also the design document https://www.notion.so/tarantool/Schemafull-IPROTO-cc315ad6bdd641dea66ad854992d8cbf?pvs=4#6f74f0c70005463b8438830edd1a0117.
Requested by @CuriousGeorgiy in https://github.com/tarantool/tarantool/commit/dc26e47e1bacb3148bc3fc5753cc1c82afb521ef.

Definition of Done

• The box.tuple reference contains the new functions
• Decide on other content, for example, a how-to somewhere in Concepts / Data model
• Add a "see also" link to the compat option page on the compat.box_tuple_new_vararg description in the configuration reference

Start with the box.tuple reference linked in the issue and the compat.box_tuple_new_vararg page. Document the format functions, standalone tuple options, and changed constructor behavior, then add a see-also link from the configuration reference. Check the existing Concepts/Data model structure before deciding whether a how-to belongs there.