doc: miscellaneous refinements

README.rst

@@ -33,8 +33,8 @@ or viewed by people. It organizes the data into a nested collection of
 dictionaries, lists, and strings without the need for quoting or escaping.  
 A unique feature of this file format is that it only supports one scalar type: 
 strings.  While the decision to eschew integer, real, date, etc. types may seem 
-counter intuitive, it leads to simpler data files and applications that are 
-:ref:`more robust <only_strings>`.
+counter intuitive, it leads to simpler data files and applications that are more 
+robust.
 
 *NestedText* is convenient for configuration files, address books, account 
 information, and the like.  Because there is no need for quoting or escaping, it 

doc/alternatives.rst

@@ -238,7 +238,7 @@ code more robust with little to no increase in complexity:
 .. collapse:: Schemas make data conversions easy.
 
     For robustness, all data should be validated when reading it to assure there 
-    are no errors.  This is conveniently and efficiently performed with 
+    are no errors.  This is performed conveniently and efficiently with 
     a :ref:`schema <schemas>`.  Schemas are used to specify the expected type 
     for each value and are easily extended to perform type conversion as needed.  
     For example, if a particular value should be an integer but a string is 

doc/basic_syntax.rst

@@ -4,9 +4,9 @@ Language introduction
 
 This is a overview of the syntax of a *NestedText* document, which consists of 
 a :ref:`nested collection <nesting>` of :ref:`dictionaries <dictionaries>`, 
-:ref:`lists <lists>`, and :ref:`strings <strings>`.  All leaf values must be 
-simple text or empty. You can find more specifics :ref:`later on <nestedtext 
-file format>`.
+:ref:`lists <lists>`, and :ref:`strings <strings>` where indentation is used to 
+indicate nesting.  All leaf values must be simple text or empty. You can find 
+more specifics :ref:`in the next section <nestedtext file format>`.
 
 
 .. _dictionaries:
@@ -27,9 +27,10 @@ dictionary items in which the keys all begin at the same level of indentation.
 There are several different ways to specify dictionaries.
 
 In the first form, the key and value are separated with a colon (``:``) followed 
-by either a space or a newline.  The key must be a string and must not contain 
-newline characters, leading spaces, or the ``:␣`` character sequence.  Any 
-spaces between the key and the colon are ignored.
+by either a space or a newline.  The key must be a string and must not start 
+with a ``-``, ``>``, ``:``, ``[``, ``{`` or space character; or contain newline 
+characters or the ``:␣`` character sequence.  Any spaces between the key and the 
+colon that separates the key from the value are ignored.
 
 The value of this dictionary item may be a rest-of-line string, a multiline 
 string, a list, or a dictionary. If it is a rest-of-line string, it contains all 
@@ -42,14 +43,15 @@ on the next line, which must be further indented.
 
     key 1: value 1
     key 2:
-        - value 2a
-        - value 2b
     key 3:
-        key 3a: value 3a
-        key 3b: value 3b
+        - value 3a
+        - value 3b
     key 4:
-        > first line of value 4
-        > second line of value 4
+        key 4a: value 4a
+        key 4b: value 4b
+    key 5:
+        > first line of value 5
+        > second line of value 5
 
 A second less common form of a dictionary item employs multiline keys.  In this 
 case there are no limitations on the key other than it be a string.  Each line 
@@ -122,14 +124,15 @@ line, which must be further indented.
 
     - value 1
     -
-        - value 2a
-        - value 2b
     -
-        key 3a: value 3a
-        key 3b: value 3b
+        - value 3a
+        - value 3b
+    -
+        key 4a: value 4a
+        key 4b: value 4b
     -
-        > first line of value 4
-        > second line of value 4
+        > first line of value 5
+        > second line of value 5
 
 Another form of a list is the inline list.  This is a compact form where all the 
 list items are given on the same line.  There is a bit of syntax that defines 
@@ -162,9 +165,10 @@ Strings
 =======
 
 There are three types of strings: rest-of-line strings, multiline strings, and 
-inline strings.  Rest-of-line strings are simply all the remaining characters on 
-the line, including any leading or trailing white space.  They can contain any 
-character other than a newline:
+inline strings.  Rest-of-line strings are simply all the characters on a line 
+that follow a list tag (``-␣``) or dictionary tag (``:␣``), including any 
+leading or trailing white space.  They can contain any character other than 
+a newline:
 
 .. code-block:: nestedtext
 
@@ -202,7 +206,7 @@ retained, along with all newlines except the last.
 
 Inline strings are the string values specified in inline dictionaries and lists.  
 They are somewhat constrained in the characters that they may contain; nothing 
-that might be confused with syntax characters used by the inline list or 
+that might be confused with the syntax characters used by the inline list or 
 dictionary that contains it.  Specifically, inline strings may not contain 
 newlines or any of the following characters: ``[``, ``]``, ``{``, ``}``, or 
 ``,``.  In addition, inline strings that are contained in inline dictionaries 
@@ -282,7 +286,8 @@ NestedText Files
 ================
 
 *NestedText* files should be encoded with `UTF-8 
-<https://en.wikipedia.org/wiki/UTF-8>`_.
+<https://en.wikipedia.org/wiki/UTF-8>`_.  The top-level object must not be 
+indented.
 
 The name used for the file is arbitrary but it is tradition to use a
 .nt suffix.  If you also wish to further distinguish the file type

doc/basic_use.rst

@@ -61,6 +61,10 @@ default. You can also specify 'list', 'str', or 'any' (or *dict*, *list*, *str*,
 or *any*).  All but 'any' constrain the data type of the top-level of the 
 *NestedText* content.
 
+The *load* functions provide a *keymap* argument that is useful for adding line 
+numbers to error message.  This feature is demonstrated in :ref:`voluptuous 
+example`.
+
 More advanced usage is described in :meth:`loads`.
 
 NestedText Writer

doc/file_format.rst

@@ -37,11 +37,12 @@ The *NestedText* format follows a small number of simple rules. Here they are.
 
 **Line-type tags**:
 
-    Most remaining lines are identified by the presence of tags, where a tag is
-    the first dash (``-``), colon (``:``), or greater-than symbol (``>``) on 
-    a line when followed immediately by a space or line break, or a hash 
-    {``#``), left bracket (``[``), or left brace (``{``) as the first non-white 
-    space character on a line.
+    Most remaining lines are identified by the presence of tags, where a tag is:
+
+    #.  the first dash (``-``), colon (``:``), or greater-than symbol (``>``) on 
+        a line when followed immediately by a space or line break;
+    #.  or a hash {``#``), left bracket (``[``), or left brace (``{``) as the 
+        first non-white space character on a line.
 
     Most of these symbols only introduce tags when they are the first non-space 
     character on a line, but colon tags need not start the line.
@@ -86,15 +87,15 @@ The *NestedText* format follows a small number of simple rules. Here they are.
     type of the line and is discarded leaving the value.  The value takes one of 
     three forms.
 
-    1. If the line contains further text (characters after the dash-space), then 
+    #. If the line contains further text (characters after the dash-space), then 
        the value is that text.  The text ends at the line break and may contain 
        any other printing UTF-8 character.
 
-    2. If there is no further text on the line and the next line has greater 
+    #. If there is no further text on the line and the next line has greater 
        indentation, then the next line holds the value, which may be a list, 
        a dictionary, or a multiline string.
 
-    3. Otherwise the value is empty; it is taken to be an empty string.
+    #. Otherwise the value is empty; it is taken to be an empty string.
 
 
 **Key items**:
@@ -126,28 +127,30 @@ The *NestedText* format follows a small number of simple rules. Here they are.
 
     The inline key precedes the tag. It must be a non-empty string and must not:
 
-    1. contain a line break character.
-    2. start with a list item, string item or key item tag,
-    3. contain a dictionary item tag, or
-    4. contain leading spaces (any spaces that follow the key are ignored).
+    #. contain a line break character.
+    #. start with a list item, string item or key item tag,
+    #. start with ``[`` or ``{``,
+    #. contain a dictionary item tag, or
+    #. contain leading spaces (any spaces that follow the key are ignored).
 
     The tag is only used to determine the type of the line and is discarded 
     leaving the key and the value, which follows the tag.  The value takes one 
     of three forms.
 
-    1. If the line contains further text (characters after the colon-space), 
+    #. If the line contains further text (characters after the colon-space), 
        then the value is that text.  The text ends at the line break and may 
        contain any other printing UTF-8 character.
 
-    2. If there is no further text on the line and the next line has greater 
+    #. If there is no further text on the line and the next line has greater 
        indentation, then the next line holds the value, which may be a list, 
        a dictionary, or a multiline string.
 
-    3. Otherwise the value is empty; it is taken to be an empty string.
+    #. Otherwise the value is empty; it is taken to be an empty string.
 
     The second form of *dictionary item* is the *dictionary item with multiline 
-    key*.  It consists of a multiline key value followed by an indented 
-    multiline string, list, or dictionary.
+    key*.  It consists of a multiline key value followed by an indented value.
+    The value may be a multiline string, list, or dictionary; or an inline list 
+    or dictionary.
 
     Adjacent dictionary items of either form with the same indentation level are 
     combined in order into a dictionary.
@@ -174,13 +177,13 @@ The *NestedText* format follows a small number of simple rules. Here they are.
 
     *Inline strings* are the string values specified in inline dictionaries and 
     lists.  They are somewhat constrained in the characters that they may 
-    contain; nothing that might be confused with syntax characters used by the 
-    inline list or dictionary that contains it.  Specifically, inline strings 
-    may not contain newlines or any of the following characters: ``[``, ``]``, 
-    ``{``, ``}``, or ``,``.  In addition, inline strings that are contained in 
-    inline dictionaries may not contain ``:``.  Leading and trailing white space 
-    are ignored with inline strings, this includes spaces, tabs, Unicode spaces, 
-    etc.
+    contain; nothing is allowed that might be confused with the syntax 
+    characters used by the inline list or dictionary that contains it.  
+    Specifically, inline strings may not contain newlines or any of the 
+    following characters: ``[``, ``]``, ``{``, ``}``, or ``,``.  In addition, 
+    inline strings that are contained in inline dictionaries may not contain 
+    ``:``.  Leading and trailing white space are ignored with inline strings, 
+    this includes spaces, tabs, Unicode spaces, etc.
 
     Both inline lists and dictionaries may be empty, and represent the only way 
     to represent empty lists or empty dictionaries in *NestedText*.  An empty 

doc/releases.rst

@@ -17,14 +17,19 @@ Latest development version
 | Released: 2021-07-23
 
 
+v3.2 (2022-01-17)
+-----------------
+
+- add cyclic reference detection and reporting.
+
+
 v3.1 (2021-07-23)
 -----------------
 
 - change error reporting for :func:`dumps` and :func:`dump` functions;
   culprit is now the keys rather than the value.
 
 
-
 v3.0 (2021-07-17)
 -----------------
 

nestedtext.py

@@ -1374,7 +1374,7 @@ def check_for_cyclic_reference(self, obj):
         if id(obj) in self.values[:-1]:
             raise NestedTextError(
                 obj,
-                template = 'cyclic reference found: cannot be dumped.',
+                template = 'circular reference.',
                 culprit=self.keys
             )
 

tests/test_nestedtext.py

@@ -1365,11 +1365,11 @@ def test_cycle_detection():
     with pytest.raises(nt.NestedTextError) as exception:
         nt.dumps(a)
     assert exception.value.culprit == (3, 0, 3,)
-    assert 'cyclic reference' in str(exception.value)
+    assert 'circular reference' in str(exception.value)
 
     with pytest.raises(nt.NestedTextError) as exception:
         nt.dumps(A)
     assert exception.value.culprit == ('a', 3, 0)
-    assert 'cyclic reference' in str(exception.value)
+    assert 'circular reference' in str(exception.value)
 
 # vim: fdm=marker