Added docstrings for new methods; added ending location for locatedExpr

git-svn-id: svn://svn.code.sf.net/p/pyparsing/code/trunk@265 9bf210a0-9d2d-494c-87cf-cfb32e7dff7b

4 files changed, 34 insertions, 5 deletions

diff --git a/src/CHANGES b/src/CHANGES
index ff6ca36..681a7b7 100644
--- a/src/CHANGES
+++ b/src/CHANGES
@@ -8,7 +8,8 @@ Version 2.0.2 - April, 2014
   to accept "expr()" as a shortcut for "expr.copy()".

 

 - Added "locatedExpr(expr)" helper, to decorate any returned tokens

-  with their location within the input string.

+  with their location within the input string. Adds the results names

+  locn_start and locn_end to the output parse results.

 

 - Added "pprint()" method to ParseResults, to simplify troubleshooting

   and prettified output. Now instead of importing the pprint module

diff --git a/src/genEpydoc.bat b/src/genEpydoc.bat
index 1b715da..2dfa744 100644
--- a/src/genEpydoc.bat
+++ b/src/genEpydoc.bat
@@ -1 +1,2 @@
+xcopy /y .\sourceforge\svn\trunk\src\pyparsing.py .

 python c:\python26\scripts\epydoc -v --name pyparsing -o htmldoc --inheritance listed --no-private pyparsing.py

diff --git a/src/pyparsing.py b/src/pyparsing.py
index cd45a03..7dfe104 100644
--- a/src/pyparsing.py
+++ b/src/pyparsing.py
@@ -58,7 +58,7 @@ The pyparsing module handles some of the problems that are typically vexing when
 """

 

 __version__ = "2.0.2"

-__versionTime__ = "13 April 2014 11:10"

+__versionTime__ = "13 April 2014 12:10"

 __author__ = "Paul McGuire <ptmcg@users.sourceforge.net>"

 

 import string

@@ -399,6 +399,8 @@ class ParseResults(object):
             return list(self.iteritems())

 

     def haskeys( self ):

+        """Since keys() returns an iterator, this method is helpful in bypassing

+           code that looks for the existence of any defined results names."""

         return bool(self.__tokdict)

         

     def pop( self, *args, **kwargs):

@@ -651,6 +653,9 @@ class ParseResults(object):
         return "".join(out)

 

     def pprint(self, *args, **kwargs):

+        """Pretty-printer for parsed results as a list, using the C{pprint} module.

+           Accepts additional positional or keyword args as defined for the 

+           C{pprint.pprint} method. (U{http://docs.python.org/3/library/pprint.html#pprint.pprint})"""

         pprint.pprint(self.asList(), *args, **kwargs)

 

     # add support for pickle protocol

@@ -3308,9 +3313,17 @@ def ungroup(expr):
     return TokenConverter(expr).setParseAction(lambda t:t[0])

 

 def locatedExpr(expr):

-    """Helper to decorate a returned token with its location in the input string"""

+    """Helper to decorate 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 C{<TAB>} characters, you may want to call

+       C{L{ParserElement.parseWithTabs}}

+    """

     locator = Empty().setParseAction(lambda s,l,t: l)

-    return Group(locator("location") + expr("value"))

+    return Group(locator("locn_start") + expr("value") + locator.copy().leaveWhitespace()("locn_end"))

 

 

 # convenience constants for positional expressions

diff --git a/src/unitTests.py b/src/unitTests.py
index 915a788..f463a3b 100644
--- a/src/unitTests.py
+++ b/src/unitTests.py
@@ -2170,6 +2170,19 @@ class MarkInputLineTest(ParseTestCase):
         else:

             assert False, "test construction failed - should have raised an exception"

 

+class LocatedExprTest(ParseTestCase):

+    def runTest(self):

+

+        #             012345678901234567890123456789012345678901234567890

+        samplestr1 = "DOB 10-10-2010;more garbage;ID PARI12345678  ;more garbage"

+        

+        from pyparsing import Regex, Word, alphanums, restOfLine, locatedExpr

+        id_ref = locatedExpr("ID" + Word(alphanums,exact=12)("id"))

+

+        res = id_ref.searchString(samplestr1)[0][0]

+        print_(res.dump())

+        assert samplestr1[res.locn_start:res.locn_end] == 'ID PARI12345678', "incorrect location calculation"

+

 

 class MiscellaneousParserTests(ParseTestCase):

     def runTest(self):

@@ -2377,6 +2390,7 @@ def makeTestSuite():
     suite.addTest( SumParseResultsTest() )

     suite.addTest( WordExcludeTest() )

     suite.addTest( MarkInputLineTest() )

+    suite.addTest( LocatedExprTest() )

     suite.addTest( MiscellaneousParserTests() )

     if TEST_USING_PACKRAT:

         # retest using packrat parsing (disable those tests that aren't compatible)

@@ -2397,7 +2411,7 @@ def makeTestSuiteTemp():
     suite.addTest( PyparsingTestInit() )

     #~ suite.addTest( OptionalEachTest() )

     #~ suite.addTest( RepeaterTest() )

-    suite.addTest( MarkInputLineTest() )

+    suite.addTest( LocatedExprTest() )

         

     return suite