From 746408560b4dd13d98d855e41a53ee54657aa182 Mon Sep 17 00:00:00 2001
From: ocelot-inc <pgulutzan@ocelot.ca>
Date: Fri, 18 Sep 2015 11:54:53 -0600
Subject: [PATCH] connectors: updated examples
---
doc/sphinx/book/connectors/__c.rst | 8 ++++----
doc/sphinx/book/connectors/__perl.rst | 10 +++++-----
doc/sphinx/book/connectors/__php.rst | 22 ++++++----------------
doc/sphinx/book/connectors/__python.rst | 16 ++++++++--------
doc/sphinx/book/connectors/index.rst | 18 ++++++++++--------
5 files changed, 33 insertions(+), 41 deletions(-)
diff --git a/doc/sphinx/book/connectors/__c.rst b/doc/sphinx/book/connectors/__c.rst
index 75f51e6f57..c785721f0d 100644
--- a/doc/sphinx/book/connectors/__c.rst
+++ b/doc/sphinx/book/connectors/__c.rst
@@ -2,8 +2,8 @@
C
=====================================================================
-Here is a complete C program that inserts ``[99999,'B']`` into
-space ``examples`` via the high-level C API.
+Here is a complete C program that inserts :code:`[99999,'B']` into
+space :code:`examples` via the high-level C API.
.. code-block:: c
@@ -43,8 +43,8 @@ To compile and link the program, say: |br|
|nbsp| |nbsp| :codenormal:`#Sometimes this is necessary: export LD_LIBRARY_PATH=/usr/local/lib` |br|
|nbsp| |nbsp| :codenormal:`gcc -o example example.c -ltarantool -ltarantoolnet` |br|
Before trying to run,
-check that the server is listening and that :code:`examples` exists, as described at the start of this chapter.
-To run the program, say ``./example``. The program will connect
+check that the server is listening and that :code:`examples` exists, as :ref:`described earlier <connector-setting>`.
+To run the program, say :code:`./example`. The program will connect
to the server, and will send the request.
If tarantool is not running on localhost with listen address = 3301, the program will print “Connection refusedâ€.
If the insert fails, the program will print "Insert failed" and an error number.
diff --git a/doc/sphinx/book/connectors/__perl.rst b/doc/sphinx/book/connectors/__perl.rst
index 2ba37653b2..16dad2e5fa 100644
--- a/doc/sphinx/book/connectors/__perl.rst
+++ b/doc/sphinx/book/connectors/__perl.rst
@@ -21,8 +21,8 @@ example, on Ubuntu, the installation could look like this:
Here is a complete Perl program that inserts [99999,'BB'] into space[999] via
the Perl API. Before trying to run, check that the server is listening and
-that ``examples`` exists, as `described earlier`_. To run, paste the code into
-a file named example.pl and say ``perl example.pl``. The program will connect
+that :code:`examples` exists, as :ref:`described earlier <connector-setting>`. To run, paste the code into
+a file named example.pl and say :code:`perl example.pl`. The program will connect
using an application-specific definition of the space. The program will open a
socket connection with the tarantool server at localhost:3301, then send an
INSERT request, then — if all is well — end without displaying any messages.
@@ -38,14 +38,14 @@ will print “Connection refusedâ€.
my $tnt = DR::Tarantool::MsgPack::SyncClient->connect(
host => '127.0.0.1', # look for tarantool on localhost
- port => 3301, # assume tarantool listen address = default
+ port => 3301, # on port 3301
user => 'guest', # username. one could also say 'password=>...'
spaces => {
999 => { # definition of space[999] ...
name => 'examples', # space[999] name = 'examples'
default_type => 'STR', # space[999] field type is 'STR' if undefined
- fields => [ { # definition of space[512].fields ...
+ fields => [ { # definition of space[999].fields ...
name => 'field1', type => 'NUM' } ], # space[999].field[1] name='field1',type='NUM'
indexes => { # definition of space[999] indexes ...
0 => {
@@ -58,4 +58,4 @@ necessary for good practice. For that, please see `DR::Tarantool`_ CPAN reposito
.. _DR::Tarantool: http://search.cpan.org/~unera/DR-Tarantool/
.. _CPAN, the Comprehensive Perl Archive Network: https://en.wikipedia.org/wiki/Cpan
-.. _described earlier: https://en.wikipedia.org/wiki/Cpan
+
diff --git a/doc/sphinx/book/connectors/__php.rst b/doc/sphinx/book/connectors/__php.rst
index aa42ae761a..3661c8a235 100644
--- a/doc/sphinx/book/connectors/__php.rst
+++ b/doc/sphinx/book/connectors/__php.rst
@@ -20,21 +20,15 @@ the installation could look like this:
make
# make install is optional
-At this point there is a file named ``~/tarantool-php/modules/tarantool.so``.
-PHP will only find it if the PHP initialization file ``php.ini`` contains a
-line like ``extension=./tarantool.so``. So copy ``tarantool.so`` to the working
-directory and tell PHP where to find the ``php.ini`` file that contains that line ...
-
-.. code-block:: bash
-
- cd ~
- cp ./tarantool-php/modules/tarantool.so .
- export PHP_INI_SCAN_DIR=~/tarantool-php/test/shared
+At this point there is a file named :code:`~/tarantool-php/modules/tarantool.so`.
+PHP will only find it if the PHP initialization file :code:`php.ini` contains a
+line like :code:`extension=./tarantool.so`, or if PHP is started with the option
+:code:`-d extension=~/tarantool-php/modules/tarantool.so`.
Here is a complete PHP program that inserts [99999,'BB'] into a space named 'examples'
via the PHP API. Before trying to run, check that the server is listening and that
-``examples`` exists, as described at the start of this chapter. To run, paste the code into a file named
-example.php and say ``php example.php``. The program will open a socket connection with
+:code:`examples` exists, as :ref:`described earlier <connector-setting>`. To run, paste the code into a file named
+example.php and say :code:`php -d extension=~/tarantool-php/modules/tarantool.so example.php`. The program will open a socket connection with
the tarantool server at localhost:3301, then send an INSERT request, then — if all is
well — print "Insert succeeded". If the tuple already exists, the program will print
“Duplicate key exists in unique index 'primary' in space 'examples'â€.
@@ -52,10 +46,6 @@ well — print "Insert succeeded". If the tuple already exists, the program will
}
?>
-After running the example, it is good practice to delete the file ./tarantool.so,
-since it is only compatible with PHP and its existence could confuse non-PHP
-applications.
-
The example program only shows one command and does not show all that's necessary
for good practice. For that, please see `tarantool-php`_ project at GitHub.
diff --git a/doc/sphinx/book/connectors/__python.rst b/doc/sphinx/book/connectors/__python.rst
index 2230269589..6563c1bb8b 100644
--- a/doc/sphinx/book/connectors/__python.rst
+++ b/doc/sphinx/book/connectors/__python.rst
@@ -2,8 +2,8 @@
Python
=====================================================================
-Here is a complete Python program that inserts ``[99999,'Value','Value']`` into
-space ``examples`` via the high-level Python API.
+Here is a complete Python program that inserts :code:`[99999,'Value','Value']` into
+space :code:`examples` via the high-level Python API.
.. code-block:: python
@@ -15,14 +15,14 @@ space ``examples`` via the high-level Python API.
print result
To prepare, paste the code into a file named example.py and install
-tarantool-python with either ``pip install tarantool\>0.4`` to install
-in ``/usr`` (requires **root** privilege) or ``pip install tarantool\>0.4 --user``
-to install in ``~`` i.e. user's default directory. Before trying to run,
-check that the server is listening and that examples exists, as described at the start of this chapter.
-To run the program, say ``python example.py``. The program will connect
+tarantool-python with either :code:`pip install tarantool\>0.4` to install
+in :code:`/usr` (requires **root** privilege) or :code:`pip install tarantool\>0.4 --user`
+to install in :code:`~` i.e. user's default directory. Before trying to run,
+check that the server is listening and that examples exists, as :ref:`described earlier <connector-setting>`.
+To run the program, say :code:`python example.py`. The program will connect
to the server, will send the request, and will not throw an exception if
all went well. If the tuple already exists, the program will throw
-``DatabaseException(“Duplicate key exists in unique indexâ€)``.
+:code:`DatabaseException(“Duplicate key exists in unique indexâ€)`.
The example program only shows one request and does not show all that's
necessary for good practice. For that, see http://github.com/tarantool/tarantool-python.
diff --git a/doc/sphinx/book/connectors/index.rst b/doc/sphinx/book/connectors/index.rst
index a7175aeb29..b186118f5d 100644
--- a/doc/sphinx/book/connectors/index.rst
+++ b/doc/sphinx/book/connectors/index.rst
@@ -20,7 +20,7 @@ carries in its header the same type and id as in the request. The id makes it
possible to match a request to a response, even if the latter arrived out of order.
Unless implementing a client driver, one needn't concern oneself with the
-complications of the binary protocol. `Language-specific drivers`_ provide a
+complications of the binary protocol. Language-specific drivers provide a
friendly way to store domain language data structures in Tarantool. A complete
description of the binary protocol is maintained in annotated Backus-Naur form
in the source tree: please see :ref:`iproto protocol`.
@@ -31,7 +31,7 @@ in the source tree: please see :ref:`iproto protocol`.
The Tarantool API exists so that a client program can send a request packet to
the server, and receive a response. Here is an example of a what the client
-would send for ``box.space[513]:insert{'A', 'BB'}``. The BNF description of the
+would send for :code:`box.space[513]:insert{'A', 'BB'}`. The BNF description of the
components is in file :ref:`iproto protocol`.
.. _Language-specific drivers: `Connectors`_
@@ -60,20 +60,22 @@ Now, one could send that packet to the tarantool server, and interpret the respo
(:ref:`iproto protocol` has a description of the packet format for responses as
well as requests). But it would be easier, and less error-prone, if one could invoke
a routine that formats the packet according to typed parameters. Something like
-``response=tarantool_routine("insert",513,"A","B");``. And that is why APIs exist for
+:code:`response=tarantool_routine("insert",513,"A","B");`. And that is why APIs exist for
drivers for Perl, Python, PHP, and so on.
+.. _connector-setting:
+
====================================================================
Setting up the server for connector examples
====================================================================
This chapter has examples that show how to connect to the Tarantool server via
-the Perl, PHP, and Python connectors. The examples contain hard code that will
+the Perl, PHP, Python, and C connectors. The examples contain hard code that will
work if and only if the server (tarantool) is running on localhost (127.0.0.1)
-and is listening on port 3301 (``box.cfg.listen='3301'``) and space 'examples'
-has id = 999 (``box.space.examples.id = 999``), and space 'examples' has a
-primary-key index for a numeric field (``box.space[999].index[0].parts[1].type
-= "NUM"``) and user 'guest' has privileges for reading and writing.
+and is listening on port 3301 (:code:`box.cfg.listen = '3301'`) and space 'examples'
+has id = 999 (:code:`box.space.examples.id = 999`), and space 'examples' has a
+primary-key index for a numeric field (:code:`box.space[999].index[0].parts[1].type
+= "NUM"`) and user 'guest' has privileges for reading and writing.
It is easy to meet all the conditions by starting the server and executing this
script:
--
GitLab