Remove old language stating that parseString returns "a list of matched strings", and clarify use of the returned ParseResults

2 files changed, 35 insertions, 4 deletions

diff --git a/README.rst b/README.rst
index fc2e323..eb1b74b 100644
--- a/README.rst
+++ b/README.rst
@@ -36,7 +36,8 @@ The Python representation of the grammar is quite readable, owing to the
 self-explanatory class names, and the use of '+', '|' and '^' operator
 definitions.
 
-The parsed results returned from ``parseString()`` can be accessed as a
+The parsed results returned from ``parseString()`` is a collection of type
+``ParseResults``, which can be accessed as a
 nested list, a dictionary, or an object with named attributes.
 
 The pyparsing module handles some of the problems that are typically
diff --git a/docs/HowToUsePyparsing.rst b/docs/HowToUsePyparsing.rst
index 7a1a841..59f159c 100644
--- a/docs/HowToUsePyparsing.rst
+++ b/docs/HowToUsePyparsing.rst
@@ -5,8 +5,8 @@ Using the pyparsing module
 :author: Paul McGuire
 :address: ptmcg@users.sourceforge.net
 
-:revision: 3.0.0
-:date: August, 2020
+:revision: 3.0.1
+:date: May, 2021
 
 :copyright: Copyright |copy| 2003-2020 Paul McGuire.
 
@@ -765,16 +765,46 @@ Other classes
       own list structure, so that the tokens can be handled as a hierarchical
       tree
 
+  - as an object
+
+    - named elements can be accessed as if they were attributes of an object:
+      if an element is referenced that does not exist, it will return ``""``.
+
   ParseResults can also be converted to an ordinary list of strings
   by calling ``asList()``.  Note that this will strip the results of any
   field names that have been defined for any embedded parse elements.
   (The ``pprint`` module is especially good at printing out the nested contents
   given by ``asList()``.)
 
-  Finally, ParseResults can be viewed by calling ``dump()``. ``dump()` will first show
+  Finally, ParseResults can be viewed by calling ``dump()``. ``dump()`` will first show
   the ``asList()`` output, followed by an indented structure listing parsed tokens that
   have been assigned results names.
 
+  Here is sample code illustrating some of these methods::
+
+    >>> number = Word(nums)
+    >>> name = Combine(Word(alphas)[...], adjacent=False, joinString=" ")
+    >>> parser = number("house_number") + name("street_name")
+    >>> result = parser.parseString("123 Main St")
+    >>> print(result)
+    ['123', 'Main St']
+    >>> print(type(result))
+    <class 'pyparsing.ParseResults'>
+    >>> print(repr(result))
+    (['123', 'Main St'], {'house_number': ['123'], 'street_name': ['Main St']})
+    >>> result.house_number
+    '123'
+    >>> result["street_name"]
+    'Main St'
+    >>> result.asList()
+    ['123', 'Main St']
+    >>> result.asDict()
+    {'house_number': '123', 'street_name': 'Main St'}
+    >>> print(result.dump())
+    ['123', 'Main St']
+    - house_number: '123'
+    - street_name: 'Main St'
+
 
 Exception classes and Troubleshooting
 -------------------------------------