Add recurse() method to simplify navigating through hierarchy of ParserElements within a pyparsing parser

3 files changed, 15 insertions, 2 deletions

diff --git a/CHANGES b/CHANGES
index d5e2fbb..ade02b2 100644
--- a/CHANGES
+++ b/CHANGES
@@ -119,6 +119,10 @@ Version 3.0.0a2 - June, 2020
     mistake when using Forwards)
     (**currently not working on PyPy**)
 
+- Added ParserElement.recurse() method to make it simpler for
+  grammar utilities to navigate through the tree of expressions in
+  a pyparsing grammar.
+
 - Fixed bug in ParseResults repr() which showed all matching
   entries for a results name, even if listAllMatches was set
   to False when creating the ParseResults originally. Reported
diff --git a/pyparsing/__init__.py b/pyparsing/__init__.py
index 117bef4..02729f5 100644
--- a/pyparsing/__init__.py
+++ b/pyparsing/__init__.py
@@ -95,7 +95,7 @@ classes inherit from. Use the docstrings for examples of how to:
 """
 
 __version__ = "3.0.0a2"
-__versionTime__ = "20 June 2020 13:38 UTC"
+__versionTime__ = "22 June 2020 22:03 UTC"
 __author__ = "Paul McGuire <ptmcg@users.sourceforge.net>"
 
 from .util import *
diff --git a/pyparsing/core.py b/pyparsing/core.py
index 0fa6f2d..1f02985 100644
--- a/pyparsing/core.py
+++ b/pyparsing/core.py
@@ -328,6 +328,9 @@ class ParserElement:
         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
@@ -2988,6 +2991,9 @@ class ParseExpression(ParserElement):
                 self.exprs = [exprs]
         self.callPreparse = False
 
+    def recurse(self):
+        return self.exprs[:]
+
     def append(self, other):
         self.exprs.append(other)
         self.strRepr = None
@@ -3649,6 +3655,9 @@ class ParseElementEnhance(ParserElement):
             self.callPreparse = expr.callPreparse
             self.ignoreExprs.extend(expr.ignoreExprs)
 
+    def recurse(self):
+        return [self.expr] if self.expr is not None else []
+
     def parseImpl(self, instring, loc, doActions=True):
         if self.expr is not None:
             return self.expr._parse(instring, loc, doActions, callPreParse=False)
@@ -3913,7 +3922,7 @@ class _MultipleMatch(ParseElementEnhance):
 
     def _setResultsName(self, name, listAllMatches=False):
         if __diag__.warn_ungrouped_named_tokens_in_collection:
-            for e in [self.expr] + getattr(self.expr, "exprs", []):
+            for e in [self.expr] + self.expr.recurse():
                 if isinstance(e, ParserElement) and e.resultsName:
                     warnings.warn(
                         "{}: setting results name {!r} on {} expression "