From a06908d27718e32856683238bc37648579f29801 Mon Sep 17 00:00:00 2001
From: ocelot-inc <pgulutzan@ocelot.ca>
Date: Fri, 11 Sep 2015 15:08:02 -0600
Subject: [PATCH] gh-963 serializer is not documented
---
doc/sphinx/book/box/box_index.rst | 2 +-
doc/sphinx/reference/json.rst | 9 +++++
doc/sphinx/reference/yaml.rst | 62 ++++++++++++++++++++-----------
3 files changed, 50 insertions(+), 23 deletions(-)
diff --git a/doc/sphinx/book/box/box_index.rst b/doc/sphinx/book/box/box_index.rst
index 95d7d8458e..c269c7009b 100644
--- a/doc/sphinx/book/box/box_index.rst
+++ b/doc/sphinx/book/box/box_index.rst
@@ -663,7 +663,7 @@ is Rectangle#2", and "Rectangle#3 is entirely inside Rectangle#2".
Now let us create a space and add an RTREE index.
- | :codebold:`s = box.schema.create_space('rectangles')`
+ | :codebold:`s = box.schema.space.create('rectangles')`
| :codebold:`i = s:create_index('primary',{type='HASH',parts={1,'NUM'}})`
| :codebold:`r = s:create_index('spatial',{type='RTREE',unique=false,parts={2,'ARRAY'}})`
diff --git a/doc/sphinx/reference/json.rst b/doc/sphinx/reference/json.rst
index 977827293e..c1533ed7c4 100644
--- a/doc/sphinx/reference/json.rst
+++ b/doc/sphinx/reference/json.rst
@@ -95,5 +95,14 @@ The json package provides JSON manipulation routines. It is based on the
| :codenormal:`- '{"field2":null,"field1":"a","field3":"c"}'`
| :codenormal:`...`
+The JSON output structure can be specified with :code:`__serialize`:
+__serialize="seq" for an array,
+__serialize="map" for a map.
+Serializing 'A' and 'B' with different __serialize values causes different results: |br|
+:codebold:`json.encode(setmetatable({'A', 'B'}, { __serialize="seq"}))` |br|
+:codenormal:`- '["A","B"]'` |br|
+:codebold:`json.encode({setmetatable({f1 = 'A', f2 = 'B'}, { __serialize="map"})})` |br|
+:codenormal:`- '[{"f2":"B","f1":"A"}]'` |br|
+
.. _Lua-CJSON package by Mark Pulford: http://www.kyne.com.au/~mark/software/lua-cjson.php
.. _the official documentation: http://www.kyne.com.au/~mark/software/lua-cjson-manual.html
diff --git a/doc/sphinx/reference/yaml.rst b/doc/sphinx/reference/yaml.rst
index aa5ad9dd2b..18aab659f3 100644
--- a/doc/sphinx/reference/yaml.rst
+++ b/doc/sphinx/reference/yaml.rst
@@ -33,27 +33,45 @@ series of non-YAML values and encodes them.
Example
=================================================
-.. code-block:: lua
-
- tarantool> yaml = require('yaml')
- ---
- ...
- tarantool> y = yaml.encode({'a',1,'b',2})
- ---
- ...
- tarantool> z = yaml.decode(y)
- ---
- ...
- tarantool> z[1],z[2],z[3],z[4]
- ---
- - a
- - 1
- - b
- - 2
- ...
- tarantool> if yaml.NULL == nil then print('hi') end
- hi
- ---
- ...
+ | :codenormal:`tarantool>` :codebold:`yaml = require('yaml')`
+ | :codenormal:`---`
+ | :codenormal:`...`
+ | :codenormal:`tarantool>` :codebold:`y = yaml.encode({'a',1,'b',2})`
+ | :codenormal:`---`
+ | :codenormal:`...`
+ | :codenormal:`tarantool>` :codebold:`z = yaml.decode(y)`
+ | :codenormal:`---`
+ | :codenormal:`...`
+ | :codenormal:`tarantool>` :codebold:`z[1],z[2],z[3],z[4]`
+ | :codenormal:`---`
+ | :codenormal:`- a`
+ | :codenormal:`- 1`
+ | :codenormal:`- b`
+ | :codenormal:`- 2`
+ | :codenormal:`...`
+ | :codenormal:`tarantool>` :codebold:`if yaml.NULL == nil then print('hi') end`
+ | :codenormal:`hi`
+ | :codenormal:`---`
+ | :codenormal:`...`
+
+The `YAML collection style <http://yaml.org/spec/1.1/#id930798>`_ can be specified with :code:`__serialize`:
+__serialize="sequence" for a Block Sequence array,
+__serialize="seq" for a Flow Sequence array,
+__serialize="mapping" for a Block Mapping map,
+__serialize="map" for a Flow Mapping map.
+Serializing 'A' and 'B' with different __serialize values causes different results: |br|
+:codebold:`yaml.encode(setmetatable({'A', 'B'}, { __serialize="sequence"}))` |br|
+:codenormal:`- A` |br|
+:codenormal:`- B` |br|
+:codebold:`yaml.encode(setmetatable({'A', 'B'}, { __serialize="seq"}))` |br|
+:codenormal:`- ['A', 'B']` |br|
+:codebold:`yaml.encode({setmetatable({f1 = 'A', f2 = 'B'}, { __serialize="map"})})` |br|
+:codenormal:`- f2: B` |br|
+:codenormal:`- f1: A` |br|
+:codebold:`yaml.encode({setmetatable({f1 = 'A', f2 = 'B'}, { __serialize="mapping"})})` |br|
+:codenormal:`- {'f2': 'B', 'f1': 'A'}` |br|
+
.. _YAML: http://yaml.org/
+
+
--
GitLab