Restructure Connectors section (#3149)

* Split the section into subparts
* Separate community-supported connectors

Author: patiencedaur

doc/book/connectors.rst

@@ -1,40 +1,30 @@
 .. _index-box_connectors:
 
--------------------------------------------------------------------------------
-                            Connectors
--------------------------------------------------------------------------------
+Connectors
+==========
 
 Connectors are APIs that allow using Tarantool with various programming languages.
 
 Connectors can be divided into two groups -- those maintained by the Tarantool team
 and those supported by the community.
 The Tarantool team maintains the :ref:`high-level C API <index_connector_c>`, the :ref:`Go <index_connector_go>`
 and :ref:`Java <index_connector_java>` connectors, and a synchronous :ref:`Python <index_connector_py>` connector.
-All other connectors are community-supported, which means that support for new Tarantool features may be delayed.
+All other connectors are :ref:`community-supported <connectors-community-supported>`, which means that support for new Tarantool features may be delayed.
 Besides, the Tarantool support team cannot prioritize issues that arise while working through these connectors.
 
-This chapter documents the following connectors:
-
-* :doc:`C++ <connectors/cxx/tntcxx_api>`
-* :ref:`Java <index_connector_java>`
-* :ref:`Go <index_connector_go>`
-* :ref:`R <index_connector_r>`
-* :ref:`Erlang <index_connector_erlang>`
-* :ref:`Perl <index_connector_perl>`
-* :ref:`PHP <index_connector_php>`
-* :ref:`Python <index_connector_py>`
-* :ref:`Node.js <index_connector_nodejs>`
-* :ref:`C# <index_connector_csharp>`
-* :ref:`C <index_connector_c>`
+This chapter documents APIs for various programming languages:
 
 ..  toctree::
-    :hidden:
+    :maxdepth: 1
 
-    C++ <connectors/cxx/tntcxx_api>
+    connectors/c
+    connectors/go
+    connectors/java
+    connectors/python
+    connectors/community
 
-=====================================================================
-                            Protocol
-=====================================================================
+Protocol
+--------
 
 Tarantool's binary protocol was designed with a focus on asynchronous I/O and
 easy integration with proxies. Each client request starts with a variable-length
@@ -55,9 +45,9 @@ in the source tree. For detailed examples and diagrams of all binary-protocol
 requests and responses, see
 :ref:`Tarantool's binary protocol <box_protocol-iproto_protocol>`.
 
-====================================================================
-                          Packet example
-====================================================================
+
+Packet example
+--------------
 
 The Tarantool API exists so that a client program can send a request packet to
 a server instance, and receive a response. Here is an example of a what the client
@@ -103,9 +93,8 @@ exist for drivers for Perl, Python, PHP, and so on.
 
 .. _index-connector_setting:
 
-====================================================================
-          Setting up the server for connector examples
-====================================================================
+Setting up the server for connector examples
+--------------------------------------------
 
 This chapter has examples that show how to connect to a Tarantool instance via
 the Perl, PHP, Python, node.js, and C connectors. The examples contain hard code that
@@ -131,44 +120,91 @@ script:
     box.schema.user.grant('guest','read,write','space','examples')
     box.schema.user.grant('guest','read','space','_space')
 
-.. _index_connector_java:
-
-.. include:: connectors/__java.rst
-
-.. _index_connector_go:
-
-.. include:: connectors/__go.rst
-
-.. _index_connector_r:
-
-.. include:: connectors/__r.rst
-
-.. _index_connector_erlang:
-
-.. include:: connectors/__erlang.rst
-
-.. _index_connector_perl:
-
-.. include:: connectors/__perl.rst
-
-.. _index_connector_php:
-
-.. include:: connectors/__php.rst
-
-.. _index_connector_py:
-
-.. include:: connectors/__python.rst
-
-.. _index_connector_nodejs:
-
-.. include:: connectors/__nodejs.rst
-
-.. _index_connector_csharp:
-
-.. include:: connectors/__csharp.rst
-
-.. _index_connector_c:
-
-.. include:: connectors/__c.rst
 
-.. include:: connectors/__results.rst
+Interpreting function return values
+-----------------------------------
+
+For all connectors, calling a function via Tarantool causes a return in the
+MsgPack format. If the function is called using the connector's API, some
+conversions may occur. All scalar values are returned as tuples (with a MsgPack
+type-identifier followed by a value); all non-scalar values are returned as a
+group of tuples (with a MsgPack array-identifier followed by the scalar values).
+If the function is called via the binary protocol command layer -- "eval" --
+rather than via the connector's API, no conversions occur.
+
+In the following example, a Lua function will be created. Since it will be
+accessed externally by a :ref:`'guest' user<box_space-user>`, a
+:doc:`grant </reference/reference_lua/box_schema/user_grant>` of an execute privilege will
+be necessary. The function returns an empty array, a scalar string, two booleans,
+and a short integer. The values are the ones described in the table
+:ref:`Common Types and MsgPack Encodings <msgpack-common_types_and_msgpack_encodings>`.
+
+..  code-block:: tarantoolsession
+
+    tarantool> box.cfg{listen=3301}
+    2016-03-03 18:45:52.802 [27381] main/101/interactive I> ready to accept requests
+    ---
+    ...
+    tarantool> function f() return {},'a',false,true,127; end
+    ---
+    ...
+    tarantool> box.schema.func.create('f')
+    ---
+    ...
+    tarantool> box.schema.user.grant('guest','execute','function','f')
+    ---
+    ...
+
+Here is a C program which calls the function. Although C is being used for the
+example, the result would be precisely the same if the calling program was
+written in Perl, PHP, Python, Go, or Java.
+
+..  code-block:: c
+
+    #include <stdio.h>
+    #include <stdlib.h>
+    #include <tarantool/tarantool.h>
+    #include <tarantool/tnt_net.h>
+    #include <tarantool/tnt_opt.h>
+    void main() {
+      struct tnt_stream *tnt = tnt_net(NULL);              /* SETUP */
+      tnt_set(tnt, TNT_OPT_URI, "localhost:3301");
+       if (tnt_connect(tnt) < 0) {                         /* CONNECT */
+           printf("Connection refused\n");
+           exit(-1);
+       }
+       struct tnt_stream *arg; arg = tnt_object(NULL);     /* MAKE REQUEST */
+       tnt_object_add_array(arg, 0);
+       struct tnt_request *req1 = tnt_request_call(NULL);  /* CALL function f() */
+       tnt_request_set_funcz(req1, "f");
+       uint64_t sync1 = tnt_request_compile(tnt, req1);
+       tnt_flush(tnt);                                     /* SEND REQUEST */
+       struct tnt_reply reply;  tnt_reply_init(&reply);    /* GET REPLY */
+       tnt->read_reply(tnt, &reply);
+       if (reply.code != 0) {
+         printf("Call failed %lu.\n", reply.code);
+         exit(-1);
+       }
+       const unsigned char *p= (unsigned char*)reply.data; /* PRINT REPLY */
+       while (p < (unsigned char *) reply.data_end)
+       {
+         printf("%x ", *p);
+         ++p;
+       }
+       printf("\n");
+       tnt_close(tnt);                                     /* TEARDOWN */
+       tnt_stream_free(arg);
+       tnt_stream_free(tnt);
+    }
+
+When this program is executed, it will print:
+
+..  code-block:: console
+
+    dd 0 0 0 5 90 91 a1 61 91 c2 91 c3 91 7f
+
+The first five bytes -- ``dd 0 0 0 5`` -- are the MsgPack encoding for
+"32-bit array header with value 5" (see
+`MsgPack specification <http://github.com/msgpack/msgpack/blob/master/spec.md>`__).
+The rest are as described in the
+table :ref:`Common Types and MsgPack Encodings <msgpack-common_types_and_msgpack_encodings>`.

doc/book/connectors/__erlang.rst

@@ -1,3 +1,5 @@
+..  _index_connector_c:
+
 C
 =
 

doc/book/connectors/__r.rst

@@ -0,0 +1,20 @@
+..  _connectors-community-supported:
+
+Community-supported connectors
+==============================
+
+This section provides information on several `community-supported connectors <https://www.tarantool.io/en/download/connectors>`_.
+Note that they may have limited support for new Tarantool features.
+
+..  toctree::
+    :maxdepth: 1
+
+    csharp
+    C++ <cxx/tntcxx_api>
+    nodejs
+    perl
+    php
+
+For Erlang, use the `Erlang tarantool driver <https://github.com/stofel/taran>`__.
+
+For R, use the `tarantoolr <https://github.com/thekvs/tarantoolr>`__ connector.

doc/book/connectors/__results.rst

@@ -1,3 +1,5 @@
+.. _index_connector_go:
+
 Go
 ==
 

doc/book/connectors/__c.rst renamed to doc/book/connectors/c.rst

@@ -1,3 +1,5 @@
+..  _index_connector_java:
+
 Java
 ====
 

doc/book/connectors/community.rst

@@ -1,3 +1,5 @@
+..  _index_connector_py:
+
 Python
 ======
 
@@ -8,7 +10,7 @@ of the Tarantool repository and must be installed separately (see below for deta
 Here is a complete Python program that inserts ``[99999,'Value','Value']`` into
 space ``examples`` via the high-level Python API.
 
-.. code-block:: python
+..  code-block:: python
 
     #!/usr/bin/python
     from tarantool import Connection