From f2f0bb9bc12d0fd236e32101b31f5b67c10aa97b Mon Sep 17 00:00:00 2001
From: Anthon van der Neut <anthon@mnt.org>
Date: Tue, 16 Oct 2018 17:13:23 +0200
Subject: add .compact() to set non-compacting for sequence/mapping within
 sequence

---
 _doc/_static/pypi.svg |   2 +-
 _doc/example.ryd      | 136 ++++++++++++++++++++++++++++++++++++--------------
 2 files changed, 100 insertions(+), 38 deletions(-)

(limited to '_doc')

diff --git a/_doc/_static/pypi.svg b/_doc/_static/pypi.svg
index 19b9de5..4b0bd1b 100644
--- a/_doc/_static/pypi.svg
+++ b/_doc/_static/pypi.svg
@@ -1 +1 @@
-<svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" width="86" height="20"><linearGradient id="b" x2="0" y2="100%"><stop offset="0" stop-color="#bbb" stop-opacity=".1"/><stop offset="1" stop-opacity=".1"/></linearGradient><clipPath id="a"><rect width="86" height="20" rx="3" fill="#fff"/></clipPath><g clip-path="url(#a)"><path fill="#555" d="M0 0h33v20H0z"/><path fill="#007ec6" d="M33 0h53v20H33z"/><path fill="url(#b)" d="M0 0h86v20H0z"/></g><g fill="#fff" text-anchor="middle" font-family="DejaVu Sans,Verdana,Geneva,sans-serif" font-size="110"> <text x="175" y="150" fill="#010101" fill-opacity=".3" transform="scale(.1)" textLength="230">pypi</text><text x="175" y="140" transform="scale(.1)" textLength="230">pypi</text><text x="585" y="150" fill="#010101" fill-opacity=".3" transform="scale(.1)" textLength="430">0.15.72</text><text x="585" y="140" transform="scale(.1)" textLength="430">0.15.72</text></g> </svg>
+<svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" width="86" height="20"><linearGradient id="b" x2="0" y2="100%"><stop offset="0" stop-color="#bbb" stop-opacity=".1"/><stop offset="1" stop-opacity=".1"/></linearGradient><clipPath id="a"><rect width="86" height="20" rx="3" fill="#fff"/></clipPath><g clip-path="url(#a)"><path fill="#555" d="M0 0h33v20H0z"/><path fill="#007ec6" d="M33 0h53v20H33z"/><path fill="url(#b)" d="M0 0h86v20H0z"/></g><g fill="#fff" text-anchor="middle" font-family="DejaVu Sans,Verdana,Geneva,sans-serif" font-size="110"> <text x="175" y="150" fill="#010101" fill-opacity=".3" transform="scale(.1)" textLength="230">pypi</text><text x="175" y="140" transform="scale(.1)" textLength="230">pypi</text><text x="585" y="150" fill="#010101" fill-opacity=".3" transform="scale(.1)" textLength="430">0.15.73</text><text x="585" y="140" transform="scale(.1)" textLength="430">0.15.73</text></g> </svg>
diff --git a/_doc/example.ryd b/_doc/example.ryd
index 5df1d5c..c8e1c5d 100644
--- a/_doc/example.ryd
+++ b/_doc/example.ryd
@@ -125,52 +125,114 @@ both mappings and sequences. For sequences the indent is counted to the
 beginning of the scalar, with the dash taking the first position of the
 indented "space".
 
-The following program with three dumps::
+You can change this default indentation by e.g. using ``yaml.indent()``:
+
+
 --- !python |
-  import sys
-  from ruamel.yaml import YAML
 
-  data = {1: {1: [{1: 1, 2: 2}, {1: 1, 2: 2}], 2: 2}, 2: 42}
+import sys
+from ruamel.yaml import YAML
+
+d = dict(a=dict(b=2),c=[3, 4])
+yaml = YAML()
+yaml.dump(d, sys.stdout)
+print('0123456789')
+yaml = YAML()
+yaml.indent(mapping=4, sequence=6, offset=3)
+yaml.dump(d, sys.stdout)
+print('0123456789')
 
-  yaml = YAML()
-  yaml.explicit_start = True
-  yaml.dump(data, sys.stdout)
-  yaml.indent(sequence=4, offset=2)
-  yaml.dump(data, sys.stdout)
 
+--- !stdout |
+
+giving::
+
+
+--- |
+
+If a block sequence or block mapping is the element of a sequence, the
+are, by default, displayed `compact
+<http://yaml.org/spec/1.2/spec.html#id2797686>`__ notation. This means
+that the dash of the "parent" sequence is on the same line as the
+first element resp. first key/value pair of the child collection.
+
+If you want either or both of these (sequence within sequence, mapping
+within sequence) to begin on the next line use ``yaml.compact()``.
+
+
+--- !python |
+
+import sys
+from ruamel.yaml import YAML
+
+d = [dict(b=2), [3, 4]]
+yaml = YAML()
+yaml.dump(d, sys.stdout)
+print('='*15)
+yaml = YAML()
+yaml.compact(seq_seq=False, seq_map=False)
+yaml.dump(d, sys.stdout)
 
-  def sequence_indent_four(s):
-      # this will fail on direclty nested lists: {1; [[2, 3], 4]}
-      levels = []
-      ret_val = ''
-      for line in s.splitlines(True):
-          ls = line.lstrip()
-          indent = len(line) - len(ls)
-          if ls.startswith('- '):
-              if not levels or indent > levels[-1]:
-                  levels.append(indent)
-              elif levels:
-                  if indent < levels[-1]:
-                      levels = levels[:-1]
-              # same -> do nothing
-          else:
-              if levels:
-                  if indent <= levels[-1]:
-                      while levels and indent <= levels[-1]:
-                          levels = levels[:-1]
-          ret_val += '  ' * len(levels) + line
-      return ret_val
 
-  yaml = YAML()
-  yaml.explicit_start = True
-  yaml.dump(data, sys.stdout, transform=sequence_indent_four)
+--- !stdout |
+
+giving::
+
+
+--- | 
+
+------
+
+The following program uses three dumps on the same data, resulting in a stream with 
+three documents:
+
+--- !python |
+import sys
+from ruamel.yaml import YAML
+
+data = {1: {1: [{1: 1, 2: 2}, {1: 1, 2: 2}], 2: 2}, 2: 42}
+
+yaml = YAML()
+yaml.explicit_start = True
+yaml.dump(data, sys.stdout)
+yaml.indent(sequence=4, offset=2)
+yaml.dump(data, sys.stdout)
+
+
+def sequence_indent_four(s):
+    # this will fail on direclty nested lists: {1; [[2, 3], 4]}
+    levels = []
+    ret_val = ''
+    for line in s.splitlines(True):
+        ls = line.lstrip()
+        indent = len(line) - len(ls)
+        if ls.startswith('- '):
+            if not levels or indent > levels[-1]:
+                levels.append(indent)
+            elif levels:
+                if indent < levels[-1]:
+                    levels = levels[:-1]
+            # same -> do nothing
+        else:
+            if levels:
+                if indent <= levels[-1]:
+                    while levels and indent <= levels[-1]:
+                        levels = levels[:-1]
+        ret_val += '  ' * len(levels) + line
+    return ret_val
+
+yaml = YAML()
+yaml.explicit_start = True
+yaml.dump(data, sys.stdout, transform=sequence_indent_four)
+
 --- !stdout |
 gives as output::
 
---- |
-The transform example was inspired by a `question posted by *nowox*
-<https://stackoverflow.com/q/44388701/1307905>`_ on
-StackOverflow.
+--- | 
+
+The transform example, in the last document, was inspired by a
+`question posted by *nowox*
+<https://stackoverflow.com/q/44388701/1307905>`_ on StackOverflow.
 
 -----
 
-- 
cgit v1.2.1