Deprecate ParserElement.validate() (Issue #444)

3 files changed, 29 insertions, 1 deletions

diff --git a/CHANGES b/CHANGES
index f3784e2..d60882a 100644
--- a/CHANGES
+++ b/CHANGES
@@ -46,6 +46,13 @@ help from Devin J. Pohly in structuring the code to enable this peaceful transit
 
       ['BEGIN', ['aaa', 'bbb', 'ccc'], 'END']
 
+- `ParserElement.validate()` is deprecated. It predates the support for left-recursive
+  parsers, and was prone to false positives (warning that a grammar was invalid when
+  it was in fact valid).  It will be removed in a future pyparsing release. In its
+  place, developers should use debugging and analytical tools, such as `ParserElement.set_debug()`
+  and `ParserElement.create_diagram()`.
+  (Raised in Issue #444, thanks Andrea Micheli!)
+
 - Added new builtin `python_quoted_string`, which will match any form
   of single-line or multiline quoted strings defined in Python. (Inspired
   by discussion with Andreas Schörgenhumer in Issue #421.)
diff --git a/pyparsing/core.py b/pyparsing/core.py
index a6858bd..1a92ca5 100644
--- a/pyparsing/core.py
+++ b/pyparsing/core.py
@@ -1904,6 +1904,11 @@ class ParserElement(ABC):
         """
         Check defined expressions for valid structure, check for infinite recursive definitions.
         """
+        warnings.warn(
+            "ParserElement.validate() is deprecated, and should not be used to check for left recursion",
+            DeprecationWarning,
+            stacklevel=2,
+        )
         self._checkRecursion([])
 
     def parse_file(
@@ -3811,6 +3816,11 @@ class ParseExpression(ParserElement):
         return self
 
     def validate(self, validateTrace=None) -> None:
+        warnings.warn(
+            "ParserElement.validate() is deprecated, and should not be used to check for left recursion",
+            DeprecationWarning,
+            stacklevel=2,
+        )
         tmp = (validateTrace if validateTrace is not None else [])[:] + [self]
         for e in self.exprs:
             e.validate(tmp)
@@ -4550,6 +4560,11 @@ class ParseElementEnhance(ParserElement):
             self.expr._checkRecursion(subRecCheckList)
 
     def validate(self, validateTrace=None) -> None:
+        warnings.warn(
+            "ParserElement.validate() is deprecated, and should not be used to check for left recursion",
+            DeprecationWarning,
+            stacklevel=2,
+        )
         if validateTrace is None:
             validateTrace = []
         tmp = validateTrace[:] + [self]
@@ -5455,6 +5470,11 @@ class Forward(ParseElementEnhance):
         return self
 
     def validate(self, validateTrace=None) -> None:
+        warnings.warn(
+            "ParserElement.validate() is deprecated, and should not be used to check for left recursion",
+            DeprecationWarning,
+            stacklevel=2,
+        )
         if validateTrace is None:
             validateTrace = []
 
diff --git a/tests/test_unit.py b/tests/test_unit.py
index 975b65b..ae9591e 100644
--- a/tests/test_unit.py
+++ b/tests/test_unit.py
@@ -9111,7 +9111,8 @@ class Test02_WithoutPackrat(ppt.TestParseResultsAsserts, TestCase):
         def testValidation(grmr, gnam, isValid):
             try:
                 grmr.streamline()
-                grmr.validate()
+                with self.assertWarns(DeprecationWarning, msg="failed to warn validate() is deprecated"):
+                    grmr.validate()
                 self.assertTrue(isValid, "validate() accepted invalid grammar " + gnam)
             except pp.RecursiveGrammarException as rge:
                 print(grmr)