added top to common mistakes

Author: Ken Kundert

doc/common_mistakes.rst

@@ -1,9 +1,18 @@
+.. hide:
+
+    >>> from inform import Inform
+    >>> ignore = Inform(prog_name=False)
+
+
 ***************
 Common mistakes
 ***************
 
 .. currentmodule:: nestedtext
 
+Two Values for One Key
+----------------------
+
 When :func:`load()` or :func:`loads()` complains of errors it is important to 
 look both at the line fingered by the error message and the one above it.  The 
 line that is the target of the error message might by an otherwise valid 
@@ -80,3 +89,55 @@ trailing whitespace.  To do so in Vim, add::
     set listchars=trail:␣
 
 to your ~/.vimrc file.
+
+
+Lists or Strings at the Top Level
+---------------------------------
+
+Most *NestedText* files start with key-value pairs at the top-level and we 
+noticed that many developers would simply assume this in their code, which would 
+result in unexpected crashes when their programs read legal *NestedText* files 
+that had either a list or a string at the top level.  To avoid this, the 
+:func:`load` and :func:`loads` functions are configured to expect a dictionary 
+at the top level by default, which results in an error being reported if 
+a dictionary key is not the first token found:
+
+.. code-block:: python
+
+    >>> import nestedtext as nt
+
+    >>> content = """
+    ... - a
+    ... - b
+    ... """
+
+    >>> try:
+    ...     print(nt.loads(content))
+    ... except nt.NestedTextError as e:
+    ...     e.report()
+    error: 2: content must start with key or brace ({).
+           2 ❬- a❭
+
+This restriction is easily removed using *top*:
+
+.. code-block:: python
+
+    >>> try:
+    ...     print(nt.loads(content, top=list))
+    ... except nt.NestedTextError as e:
+    ...     e.report()
+    ['a', 'b']
+
+The *top* argument can take any of the following values: *"dict"*, *dict*, 
+*"list"*, *list*, *"str"*, *str*, *"any"*, or *any*.  The default value is 
+*dict*.  The value given for *top* also determines the value returned by 
+:func:`load` and :func:`loads` if the *NestedText* document is empty.
+
+================ =================================
+*top*            value returned for empty document
+---------------- ---------------------------------
+*"dict"*, *dict* ``{}``
+*"list"*, *list* ``[]``
+*"str"*, *str*   ``""``
+*"any"*, *any*   *None*
+================ =================================

examples/accumulation/settings.py

@@ -84,10 +84,10 @@ def report_error(msg):
                 value = base
         elif key in schema:
             if accumulate:
-                report_error(f"setting is unsuitable for accumulation")
+                report_error("setting is unsuitable for accumulation")
             value = schema[key](value)  # cast to desired type
         else:
-            report_error(f"unknown setting")
+            report_error("unknown setting")
         processed[key] = value
 
     return processed

tests/official_tests

@@ -992,6 +992,9 @@ def check_result(keys, expected, addresses):
         ◊  7 ❬        > Topeka, Kansas 20697❭
                                 ▲
     """, bolm='◊', strip_nl="b")
+    with pytest.raises(IndexError) as exception:
+        loc.as_line('value', offset=(2,8))
+    assert exception.value.args == (2,)
 
 
 # test_keymaps_with_duplicates {{{2