Collapse _checkRecursion methods; moved 3.0.0 summary from CHANGES to whats_new_in_3_0_0.rst; cleaned up docstrings, Word() examples, restored setName() docstring; added example to ParseException.explain()

2 files changed, 28 insertions, 20 deletions

diff --git a/pyparsing/core.py b/pyparsing/core.py
index afef674..10891d4 100644
--- a/pyparsing/core.py
+++ b/pyparsing/core.py
@@ -328,9 +328,6 @@ class ParserElement(ABC):
         self.callPreparse = True  # used to avoid redundant calls to preParse
         self.callDuringTry = False
 
-    def recurse(self):
-        return []
-
     def copy(self):
         """
         Make a copy of this :class:`ParserElement`.  Useful for defining
@@ -1449,7 +1446,7 @@ class ParserElement(ABC):
         is shown. Then if the parse succeeds, a ``"Matched"`` message is shown, or an ``"Exception raised"``
         message is shown. Also note the use of :class:`setName` to assign a human-readable name to the expression,
         which makes debugging and exception messages easier to understand - for instance, the default
-        name created for the :class:`Word` expression without calling ``setName`` is ``"W:(ABCD...)"``.
+        name created for the :class:`Word` expression without calling ``setName`` is ``"W:(A-Za-z)"``.
         """
         if flag:
             self.setDebugActions(
@@ -1475,6 +1472,12 @@ class ParserElement(ABC):
         pass
 
     def setName(self, name):
+        """
+        Define name for this expression, makes debugging and exception messages clearer.
+        Example::
+            Word(nums).parseString("ABC")  # -> Exception: Expected W:(0-9) (at char 0), (line:1, col:1)
+            Word(nums).setName("integer").parseString("ABC")  # -> Exception: Expected integer (at char 0), (line:1, col:1)
+        """
         self.customName = name
         self.errmsg = "Expected " + self.name
         if __diag__.enable_debug_on_named_expressions:
@@ -1497,8 +1500,13 @@ class ParserElement(ABC):
         self._defaultName = None
         return self
 
+    def recurse(self):
+        return []
+
     def _checkRecursion(self, parseElementList):
-        pass
+        subRecCheckList = parseElementList[:] + [self]
+        for e in self.recurse():
+            e._checkRecursion(subRecCheckList)
 
     def validate(self, validateTrace=None):
         """
@@ -3351,11 +3359,6 @@ class Or(ParseExpression):
     def _generateDefaultName(self):
         return "{" + " ^ ".join(str(e) for e in self.exprs) + "}"
 
-    def _checkRecursion(self, parseElementList):
-        subRecCheckList = parseElementList[:] + [self]
-        for e in self.exprs:
-            e._checkRecursion(subRecCheckList)
-
     def _setResultsName(self, name, listAllMatches=False):
         if __diag__.warn_multiple_tokens_in_named_alternation:
             if any(isinstance(e, And) for e in self.exprs):
@@ -3452,11 +3455,6 @@ class MatchFirst(ParseExpression):
     def _generateDefaultName(self):
         return "{" + " | ".join(str(e) for e in self.exprs) + "}"
 
-    def _checkRecursion(self, parseElementList):
-        subRecCheckList = parseElementList[:] + [self]
-        for e in self.exprs:
-            e._checkRecursion(subRecCheckList)
-
     def _setResultsName(self, name, listAllMatches=False):
         if __diag__.warn_multiple_tokens_in_named_alternation:
             if any(isinstance(e, And) for e in self.exprs):
@@ -3631,11 +3629,6 @@ class Each(ParseExpression):
     def _generateDefaultName(self):
         return "{" + " & ".join(str(e) for e in self.exprs) + "}"
 
-    def _checkRecursion(self, parseElementList):
-        subRecCheckList = parseElementList[:] + [self]
-        for e in self.exprs:
-            e._checkRecursion(subRecCheckList)
-
 
 class ParseElementEnhance(ParserElement):
     """Abstract subclass of :class:`ParserElement`, for combining and
diff --git a/pyparsing/exceptions.py b/pyparsing/exceptions.py
index 51eed66..2a10180 100644
--- a/pyparsing/exceptions.py
+++ b/pyparsing/exceptions.py
@@ -163,6 +163,21 @@ class ParseBaseException(Exception):
 
         Returns a multi-line string listing the ParserElements and/or function names in the
         exception's stack trace.
+
+        Example::
+
+            expr = pp.Word(pp.nums) * 3
+            try:
+                expr.parseString("123 456 A789")
+            except pp.ParseException as pe:
+                print(pe.explain(depth=0))
+
+        prints::
+
+            123 456 A789
+                    ^
+            ParseException: Expected W:(0-9), found 'A'  (at char 8), (line:1, col:9)
+
         """
         return self.explain_exception(self, depth)