Fixes gh-101 Document module

Author: pgulutzan

sphinx/dev_guide/internals.rst

@@ -1,5 +1,7 @@
 .. _internals:
 
+.. _internals-data_persistence:
+
 --------------------------------------------------------------------------------
 Data persistence and the WAL file format
 --------------------------------------------------------------------------------

sphinx/reference/reference_lua/errcodes.rst

@@ -74,6 +74,12 @@ robust when there are errors, particularly database errors.
    say |br|
    :samp:`if pcall(box.space.{space-name}:{function-name}() ...`
 
+   For some Tarantool box functions, pcall also returns error details
+   including a file-name and line-number within Tarantool's source code.
+   This can be seen by unpacking. For example: |br|
+   ``x, y = pcall(function() box.schema.space.create('') end)`` |br|
+   ``y:unpack()``
+
    See the tutorial :ref:`Sum a JSON field for all tuples <c_lua_tutorial-sum_a_json_field>`
    to see how pcall can fit in an application.
 

sphinx/reference/reference_lua/index.rst

@@ -40,6 +40,7 @@ This reference covers Tarantool's built-in Lua modules.
     tap
     tarantool
     uuid
+    xlog
     yaml
     other
     errcodes

sphinx/reference/reference_lua/msgpack.rst

@@ -62,6 +62,8 @@ takes a series of non-MsgPack values and encodes them.
     - [20, null, 20]
     ...
 
+.. _msgpack-serialize:
+
 The MsgPack output structure can be specified with ``__serialize``:
 
 * ``__serialize = "seq" or "sequence"`` for an array

sphinx/reference/reference_lua/xlog.rst

@@ -0,0 +1,57 @@
+.. _xlog:
+
+-------------------------------------------------------------------------------
+                            Module `xlog`
+-------------------------------------------------------------------------------
+
+The xlog module contains one function: pairs().
+It can be used to read Tarantool's snapshot files
+or write-ahead-log (WAL) files.
+A description of the file format is in section
+:ref:`Data persistence and the WAL file format <internals-data_persistence>`.
+
+.. _box_index-index_pairs:
+
+.. method:: pairs([file-name])
+
+    Open a file, 
+    and allow iterating over one file entry at a time.
+
+    Return: `iterator <https://www.lua.org/pil/7.1.html>`_ which can be used in a for/end loop.
+
+    Possible errors: File does not contain properly formatted snapshot or write-ahead-log information.
+
+    Example:
+
+    This will read the first write-ahead-log (WAL) file that was
+    created in the :ref:`wal_dir <cfg_basic-wal_dir>` directory by the
+    introductory sandbox exercise
+    ":ref:`Starting Tarantool and making your first database <user_guide_getting_started-first_database>`“.
+
+    Each result from ``pairs()`` is formatted with MsgPack
+    so its structure can be specified with :ref:`__serialize <msgpack-serialize>`.
+
+    .. code-block:: none
+
+        xlog = require('xlog')
+        t = {}
+        for k, v in xlog.pairs('00000000000000000000.xlog') do
+          table.insert(t, setmetatable(v, { __serialize = "map"}))
+          end
+        return t
+
+    The first lines of the result will look like:
+
+    .. code-block:: none 
+
+        ...
+        ---
+        - - {'BODY':   {'space_id': 272, 'index_base': 1, 'key': ['max_id'],
+                        'tuple': [['+', 2, 1]]},
+             'HEADER': {'type': 'UPDATE', 'timestamp': 1477846870.8541,
+                        'lsn': 1, 'server_id': 1}}
+          - {'BODY':   {'space_id': 280,
+                         'tuple': [512, 1, 'tester', 'memtx', 0, {}, []]},
+             'HEADER': {'type': 'INSERT', 'timestamp': 1477846870.8597,
+                        'lsn': 2, 'server_id': 1}}
+