From 2ecdf0d5cb5236b1b92e41b611ef10c3d027e45d Mon Sep 17 00:00:00 2001
From: ocelot-inc <pgulutzan@ocelot.ca>
Date: Thu, 7 Nov 2013 17:03:34 -0700
Subject: [PATCH] new appendix client-reference.xml
---
doc/user/client-reference.xml | 407 ++++++++++++++++++++++++++++++++++
doc/user/user.xml | 1 +
2 files changed, 408 insertions(+)
create mode 100644 doc/user/client-reference.xml
diff --git a/doc/user/client-reference.xml b/doc/user/client-reference.xml
new file mode 100644
index 0000000000..c958793541
--- /dev/null
+++ b/doc/user/client-reference.xml
@@ -0,0 +1,407 @@
+<appendix xmlns="http://docbook.org/ns/docbook" version="5.0"
+ xmlns:xlink="http://www.w3.org/1999/xlink"
+ xml:id="client-reference">
+
+<title>Client reference</title>
+
+<para>
+This appendix shows all legal syntax for the tarantool command-line client, with short notes and examples.
+Other client programs may have similar options and statement syntaxes.
+</para>
+
+<para>
+<bridgehead renderas="sect4">Conventions used in this appendix</bridgehead>
+
+Tokens are character sequences which are treated as syntactic units within statements.
+
+Square brackets <code>[</code> and <code>]</code> enclose optional syntax.
+Three dots in a row <code>...</code> mean the preceding tokens may be repeated.
+A vertical bar <code>|</code> means the preceding and following tokens are mutually exclusive alternatives.
+</para>
+
+<para>
+<bridgehead renderas="sect4">Options when starting client from the command line</bridgehead>
+
+General form: <code>tarantool [<replaceable>option</replaceable>...] [<replaceable>statement</replaceable>]</code>.
+
+Statement will be described in a later section.
+Option is one of the following (in alphabetical order by the long form of the option):
+</para>
+
+<variablelist>
+ <varlistentry>
+ <term xml:id="client-reference-admin-port" xreflabel="client-reference-admin-port">--admin-port</term>
+ <listitem><para>
+ Syntax: short form: <code>-a <replaceable>port-number</replaceable></code>
+ long form: <code>--a[dmin-port] [=] <replaceable>port-number</replaceable></code>.
+ Effect: Client will look for the server on the port designated by port-number.
+ Notes: The administrative port is normally set to 33015 in the server configuration file.
+ </para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term xml:id="client-reference-bin" xreflabel="client-reference-bin">--bin</term>
+ <listitem><para>
+ Syntax: short form: <code>-B</code>
+ long form: <code>--b[in]</code>.
+ Effect: When displaying with the Lua printer, treat values with
+ type NUM as if they are type STR, unless they are arguments
+ in updates used for arithmetic.
+ Example: <code>--bin</code>
+ </para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term xml:id="client-reference-cat" xreflabel="client-reference-cat">--cat</term>
+ <listitem><para>
+ Syntax: short form: <code>-C <replaceable>file-name</replaceable></code>
+ long form: <code>--c[at] <replaceable>file-name</replaceable></code>.
+ Effect: Client will print the contents of the write-ahead log or snapshot designated by file-name.
+ Example: <code>--cat /tarantool_user/work_dir/00000000000000000018.xlog</code>
+ Notes: The client stops after displaying the contents.
+ </para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term xml:id="client-reference-delim" xreflabel="client-reference-delim">--delim</term>
+ <listitem><para>
+ Syntax: short form: <code>-D <replaceable>delimiter</replaceable></code>
+ long form: <code>--d[elim] <replaceable>delimiter</replaceable></code>.
+ Effect: If --cat is used, then put delimiter at end of each line
+ of a Lua file. If --cat is not used, then require that
+ all statements end with delimiter.
+ Example: <code>--delim = '!'</code>
+ Notes: See also the SETOPT DELIMITER statement.
+ </para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term xml:id="client-reference-format" xreflabel="client-reference-format">--format</term>
+ <listitem><para>
+ Syntax: short form: <code>-M tarantool|raw</code>
+ long form: <code>--fo[rmat] tarantool|raw</code>.
+ Effect: set format for output from --cat
+ Example: <code>--format tarantool</code>
+ Notes: The default format is tarantool.
+ </para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term xml:id="client-reference-from" xreflabel="client-reference-from">--from</term>
+ <listitem><para>
+ Syntax: short form: <code>-F <replaceable>log-sequence-number</replaceable></code>
+ long form: <code>--fr[om] <replaceable>log-sequence-number</replaceable></code>.
+ Effect: Play only what has a a log sequence number greater than or equal to log-sequence-number.
+ Example: <code>--from 55</code>
+ Notes: see also --play and --to.
+ </para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term xml:id="client-reference-header" xreflabel="client-reference-header">--header</term>
+ <listitem><para>
+ Syntax: short form: <code>-H</code>
+ long form: <code>--hea[der]</code>.
+ Effect: Add a header if --format=raw.
+ Example: <code>--header</code>
+ Notes: the default is 'no header'.
+ </para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term xml:id="client-reference-help" xreflabel="client-reference-help">--help</term>
+ <listitem><para>
+ Syntax: short form: (none)
+ long form: <code>--hel[p]</code>.
+ Effect: Client displays a help message including a list of options.
+ Example: <code>--help</code>
+ Notes: The client stops after displaying the help.
+ </para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term xml:id="client-reference-host" xreflabel="client-reference-host">--host</term>
+ <listitem><para>
+ Syntax: short form: <code>-h <replaceable>host-name</replaceable></code>
+ long form: <code>--ho[st] [=] <replaceable>host-name</replaceable></code>.
+ Effect: Client will look for the server on the computer designated by host-name.
+ Example: <code>--host = 127.0.0.1</code>
+ Notes: default value is localhost.
+ </para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term xml:id="client-reference-play" xreflabel="client-reference-play">--play</term>
+ <listitem><para>
+ Syntax: short form: <code>-P <replaceable>file-name</replaceable></code>
+ long form: <code>--pl[ay] f<replaceable>file-name</replaceable></code>.
+ Effect: Client will tell server to replay the write-ahead log designated by file-name.
+ Example: <code>--play /tarantool_user/work_dir/00000000000000000018.xlog</code>
+ </para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term xml:id="client-reference-port" xreflabel="client-reference-port">--port</term>
+ <listitem><para>
+ Syntax: short form: <code>-p <replaceable>port-number</replaceable></code>
+ long form: <code>--po[rt] [=] <replaceable>port-number</replaceable></code>.
+ Effect: Client will look for the server on the port designated by port-number.
+ Example: <code>--port = 33013</code>
+ Notes: default value is 33013.
+ </para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term xml:id="client-reference-rpl" xreflabel="client-reference-rpl">--rpl</term>
+ <listitem><para>
+ Syntax: short form: <code>-R <replaceable>server-name</replaceable></code>
+ long form: <code>--rpl <replaceable>server-name</replaceable></code>.
+ Effect: Act as a replica for the server specified by server-name.
+ Example: <code>--rpl = wombat</code>
+ </para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term xml:id="client-reference-space" xreflabel="client-reference-space">--space</term>
+ <listitem><para>
+ Syntax: short form: <code>-S <replaceable>space-number</replaceable></code>
+ Long form: <code>--s[pace] <replaceable>space-number</replaceable></code>.
+ Effect: Play only what is applicable to the space designated by space-number.
+ Example: <code>--space 0</code>
+ </para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term xml:id="client-reference-to" xreflabel="client-reference-to">--to</term>
+ <listitem><para>
+ Syntax: short form: <code>-T <replaceable>log-sequence-number</replaceable></code>
+ long form: <code>--t[o] <replaceable>log-sequence-number</replaceable></code>.
+ Effect: Play only what has a log sequence number less than or equal to log-sequence-number.
+ Example: <code>--to 66</code>
+ Notes: see also --play and --from.
+ </para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term xml:id="client-reference-version" xreflabel="client-reference-version">--version</term>
+ <listitem><para>
+ Syntax: short form: <code>-v</code>
+ long form: <code>--v[ersion]</code>.
+ Effect: Client displays version information.
+ Example: <code>--version</code>
+ Notes: The client stops after displaying the version.
+ </para></listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+<bridgehead renderas="sect4">Tokens for use within statements</bridgehead>
+</para>
+<para>
+Keywords are: Character sequences containing only letters of the English alphabet.
+ Examples: SELECT, INTO, FIBER.
+ Notes: Keywords are case insensitive so SELECT and Select are the same thing.
+</para>
+<para>
+Tuple set identifiers are: Lower case letter 't' followed by one or more digits.
+ Examples: t0, t55.
+</para>
+<para>
+Field identifiers are: Lower case letter 'k' followed by one or more digits.
+ Examples: k0, k55.
+</para>
+<para>
+Procedure identifiers are: Any sequence of letters, digits, or underscores which is
+ legal according to the rules for Lua identifiers.
+</para>
+<para>
+String literals are: Any sequence of zero or more characters enclosed in single quotes.
+ Examples: 'Hello, world', 'A'.
+</para>
+<para>
+Numeric literals are: Character sequences containing only digits, optionally preceded by + or -.
+ Examples: 55, -.
+ Notes: Tarantool NUM data type is unsigned, so -1 is understood as a large unsigned number.
+</para>
+<para>
+Single-byte tokens are: * or , or ( or ).
+ Examples: * , ( ).
+</para>
+<para>
+Tokens must be separated from each other by one or more spaces, except that
+spaces are not necessary around single-byte tokens or string literals.
+</para>
+
+<para>
+<bridgehead renderas="sect4">Statements in alphabetical order</bridgehead>
+Although an initial statement may be entered on the tarantool command line,
+generally they are entered following the prompt in interactive mode while
+tarantool is running. (A prompt will be the name of the host and a greater-than
+sign, for example <code>localhost></code>). The end-of-statement marker is
+a newline (line feed).
+</para>
+
+<variablelist>
+ <varlistentry>
+ <term xml:id="client-reference-call" xreflabel="client-reference-call">CALL</term>
+ <listitem><para>
+ Syntax: <code>CALL <replaceable>procedure-identifier</replaceable> ()</code>.
+ Effect: The client tells the server to execute the procedure identified by procedure-identifier.
+ Example: <code>CALL proc50()</code>.
+ </para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term xml:id="client-reference-delete" xreflabel="client-reference-delete">DELETE</term>
+ <listitem><para>
+ Syntax: <code>DELETE FROM <replaceable>tuple-set-name</replaceable> WHERE <replaceable>field-name</replaceable> = <replaceable>literal</replaceable></code>.
+ Effect: Client tells server to delete the tuple identified by the WHERE clause.
+ Example: <code>DELETE FROM t0 WHERE k0='a'</code>.
+ Notes: field-name must identify the primary key.
+ </para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term xml:id="client-reference-exit" xreflabel="client-reference-exit">EXIT</term>
+ <listitem><para>
+ Syntax: <code>E[XIT]</code>.
+ Effect: The tarantool program stops.
+ Example: <code>EXIT</code>.
+ Notes: same as QUIT.
+ </para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term xml:id="client-reference-help2" xreflabel="client-reference-help2">HELP</term>
+ <listitem><para>
+ Syntax: <code>H[ELP]</code>.
+ Effect: Client displays a message including a list of possible statements.
+ Example: <code>HELP</code>.
+ </para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term xml:id="client-reference-insert" xreflabel="client-reference-insert">INSERT</term>
+ <listitem><para>
+ Syntax: <code>INSERT [INTO] <replaceable>tuple-set-identifier</replaceable> VALUES (<replaceable>literal</replaceable> [,<replaceable>literal</replaceable>...])</code>.
+ Effect: Client tells server to add the tuple consisting of the literal values.
+ Example: <code>INSERT INTO t0 VALUES ('a',0)</code>.
+ </para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term xml:id="client-reference-loadfile" xreflabel="client-reference-loadfile">LOADFILE</term>
+ <listitem><para>
+ Syntax: <code>LOADFILE <replaceable>string-literal</replaceable></code>.
+ Effect: The client loads instructions from the file identified by string-literal.
+ Example: <code>LOADFILE '/home/tarantool_user/file5.txt'</code>.
+ </para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term xml:id="client-reference-lua" xreflabel="client-reference-lua">LUA</term>
+ <listitem><para>
+ Syntax: <code>LUA <replaceable>token</replaceable> [<replaceable>token</replaceable>...]</code>.
+ Effect: Client tells server to execute the tokens as Lua statements.
+ Example: <code>LUA "hello".." world"</code>.
+ </para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term xml:id="client-reference-notee" xreflabel="client-reference-notee">NOTEE</term>
+ <listitem><para>
+ Syntax: <code>NOTEE</code>.
+ Effect: Client ceases to write to a file, thus canceling the effect of the TEE statement.
+ Example: <code>NOTEE</code>.
+ </para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term xml:id="client-reference-ping" xreflabel="client-reference-ping">PING</term>
+ <listitem><para>
+ Syntax: <code>PING</code>.
+ Effect: Client sends a ping to the server.
+ Example: <code>PING</code>.
+ </para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term xml:id="client-reference-quit" xreflabel="client-reference-quit">QUIT</term>
+ <listitem><para>
+ Syntax: <code>Q[UIT]</code>.
+ Effect: The client stops.
+ Example: <code>QUIT</code>.
+ Notes: same as EXIT.
+ </para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term xml:id="client-reference-reload" xreflabel="client-reference-reload">RELOAD</term>
+ <listitem><para>
+ Syntax: <code>RELOAD CONFIGURATION</code>.
+ Effect: Client tells server to re-read the configuration file.
+ Example: <code>RELOAD CONFIGURATION</code>.
+ Notes: The client sends to the server's administrative port.
+ </para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term xml:id="client-reference-replace" xreflabel="client-reference-replace">REPLACE</term>
+ <listitem><para>
+ Syntax; <code>REPLACE [INTO] <replaceable>tuple-set-identifier</replaceable> VALUES (<replaceable>literal</replaceable> [,<replaceable>literal</replaceable>...])</code>.
+ Effect: Client tells server to add the tuple consisting of the literal values.
+ Example: <code>REPLACE INTO t0 VALUES ('a',0)</code>.
+ Notes: REPLACE and INSERT are the same, except that INSERT will return an error if a tuple already exists with the same primary key.
+ </para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term xml:id="client-reference-save" xreflabel="client-reference-save">SAVE</term>
+ <listitem><para>
+ Syntax: <code>SAVE COREDUMP | SNAPSHOT</code>.
+ Effect: Client tells server to save the designated object.
+ Example: <code>SAVE SNAPSHOT</code>.
+ Notes: The client sends to the server's administrative port.
+ </para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term xml:id="client-reference-select" xreflabel="client-reference-select">SELECT</term>
+ <listitem><para>
+ Syntax: <code>SELECT * FROM <replaceable>tuple-set-identifier</replaceable> WHERE <replaceable>field-identifier</replaceable> = <replaceable>literal</replaceable> [AND|OR <replaceable>field-identifier</replaceable> = <replaceable>literal</replaceable>...] [LIMIT <replaceable>numeric-literal</replaceable> [,<replaceable>numeric-literal</replaceable>]</code>].
+ Effect: Client tells server to find the tuple or tuples identified in the WHERE clause.
+ Example: <code>SELECT * FROM t0 WHERE k0 = 5 AND k1 = 7 LIMIT 1</code>.
+ </para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term xml:id="client-reference-set" xreflabel="client-reference-set">SET</term>
+ <listitem><para>
+ Syntax: <code>SET INJECTION <replaceable>name-token</replaceable> <replaceable>state-token</replaceable></code>.
+ Effect: In normal mode: error.
+ Notes: This statement is only available in debug mode.
+ </para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term xml:id="client-reference-setopt" xreflabel="client-reference-setopt">SETOPT</term>
+ <listitem><para>
+ Syntax: <code>SETOPT DELIMITER = <replaceable>string-literal</replaceable></code>.
+ The string must be a value in single quotes.
+ Effect: string becomes end-of-statement delimiter, so newline alone is not treated as end of statement.
+ Example: <code>SETOPT DELIMITER = '!'</code>.
+ </para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term xml:id="client-reference-show" xreflabel="client-reference-show">SHOW</term>
+ <listitem><para>
+ Syntax: <code>SHOW CONFIGURATION | FIBER | INFO | INJECTIONS | PALLOC | PLUGINS | SLAB | STAT</code>.
+ Effect: The client asks the server for information about environment or statistics.
+ Example: <code>SHOW INFO</code>.
+ Notes: The client sends to the administrative port.
+ SHOW INJECTIONS is only available in debug mode.
+ </para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term xml:id="client-reference-tee" xreflabel="client-reference-tee">TEE</term>
+ <listitem><para>
+ Syntax: <code>TEE <replaceable>string-literal</replaceable></code>.
+ Effect: The client begins logging in the file identified by string-literal.
+ Example: <code>TEE '/home/tarantool_user/log.txt'</code>.
+ Notes: TEE may also be set up via an option on the command line.
+ </para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term xml:id="client-reference-update" xreflabel="client-reference-update">UPDATE</term>
+ <listitem><para>
+ Syntax: <code>UPDATE <replaceable>tuple-set-identifier</replaceable> SET <replaceable>field-identifier</replaceable> = <replaceable>literal</replaceable> [,<replaceable>field-identifier</replaceable> = <replaceable>literal</replaceable>...] WHERE <replaceable>field-identifier</replaceable> = <replaceable>literal</replaceable></code>.
+ Effect: Client tells server to change the tuple identified in the WHERE clause.
+ Example: <code>UPDATE t1 SET k1= 'K', k2 = 7 WHERE k0 = 0</code>.
+ </para></listitem>
+ </varlistentry>
+</variablelist>
+
+<para>
+For a condensed Backus-Naur Form [BNF] description of some of the statements, see
+ <link xlink:href="https://github.com/tarantool/tarantool/blob/master/doc/box-protocol.txt"><filename>doc/box-protocol.txt</filename></link>
+ and
+ <link xlink:href="https://github.com/tarantool/tarantool/blob/master/doc/sql.txt"><filename>doc/sql.txt</filename></link>.
+</para>
+
+</appendix>
+
+<!--
+vim: tw=66 syntax=docbk
+vim: spell spelllang=en_us
+-->
diff --git a/doc/user/user.xml b/doc/user/user.xml
index e1052b869c..14e06ae211 100644
--- a/doc/user/user.xml
+++ b/doc/user/user.xml
@@ -19,6 +19,7 @@
<xi:include href="proctitle.xml"/>
<xi:include href="errcode.xml"/>
<xi:include href="limitations.xml"/>
+<xi:include href="client-reference.xml"/>
<!--
<xi:include href="faq.xml"/>
-->
--
GitLab