Deprecate `locatedExpr` in favor of new `Located` class

2 files changed, 42 insertions, 1 deletions

diff --git a/pyparsing/core.py b/pyparsing/core.py
index 0649a3c..f79c86a 100644
--- a/pyparsing/core.py
+++ b/pyparsing/core.py
@@ -3903,6 +3903,45 @@ class PrecededBy(ParseElementEnhance):
         return loc, ret
 
 
+class Located(ParseElementEnhance):
+    """
+    Decorates a returned token with its starting and ending
+    locations in the input string.
+
+    This helper adds the following results names:
+
+     - ``locn_start`` - location where matched expression begins
+     - ``locn_end`` - location where matched expression ends
+     - ``value`` - the actual parsed results
+
+    Be careful if the input text contains ``<TAB>`` characters, you
+    may want to call :class:`ParserElement.parseWithTabs`
+
+    Example::
+
+        wd = Word(alphas)
+        for match in Located(wd).searchString("ljsdf123lksdjjf123lkkjj1222"):
+            print(match)
+
+    prints::
+
+        [0, ['ljsdf'], 5]
+        [8, ['lksdjjf'], 15]
+        [18, ['lkkjj'], 23]
+
+    """
+    def parseImpl(self, instring, loc, doActions=True):
+        start = loc
+        loc, tokens = self.expr._parse(
+            instring, start, doActions, callPreParse=False
+        )
+        ret_tokens = ParseResults([start, tokens, loc])
+        ret_tokens['locn_start'] = start
+        ret_tokens['value'] = tokens
+        ret_tokens['locn_end'] = loc
+        return loc, ret_tokens
+
+
 class NotAny(ParseElementEnhance):
     """Lookahead to disallow matching with the given parse expression.
     ``NotAny`` does *not* advance the parsing position within the
diff --git a/pyparsing/helpers.py b/pyparsing/helpers.py
index cf59107..a5bc2cc 100644
--- a/pyparsing/helpers.py
+++ b/pyparsing/helpers.py
@@ -337,7 +337,9 @@ def ungroup(expr):
 
 
 def locatedExpr(expr):
-    """Helper to decorate a returned token with its starting and ending
+    """
+    (DEPRECATED - future code should use the Located class)
+    Helper to decorate a returned token with its starting and ending
     locations in the input string.
 
     This helper adds the following results names: