Stage for 2.2.1 release; add Getting Started section to module docstring; fix Literal/Keyword index error bug

3 files changed, 53 insertions, 11 deletions

diff --git a/CHANGES b/CHANGES
index 8b21b51..0b1fdd1 100644
--- a/CHANGES
+++ b/CHANGES
@@ -2,8 +2,16 @@
 Change Log

 ==========

 

-Version 2.2.1 - TBD

----------------------------

+Version 2.2.1 - September, 2018

+-------------------------------

+- Applied changes necessary to migrate hosting of pyparsing source

+  over to GitHub. Many thanks for help and contributions from hugovk,

+  jdufresne, and cngkaygusuz among others through this transition,

+  sorry it took me so long!

+

+- Fixed import of collections.abc to address DeprecationWarnings

+  in Python 3.7.

+

 - Updated oc.py example to support function calls in arithmetic

   expressions; fixed regex for '==' operator; and added packrat

   parsing. Raised on the pyparsing wiki by Boris Marin, thanks!

@@ -11,6 +19,14 @@ Version 2.2.1 - TBD
 - Fixed bug in select_parser.py example, group_by_terms was not

   reported. Reported on SF bugs by Adam Groszer, thanks Adam!

 

+- Added "Getting Started" section to the module docstring, to 

+  guide new users to the most common starting points in pyparsing's

+  API.

+

+- Fixed bug in Literal and Keyword classes, which erroneously

+  raised IndexError instead of ParseException.

+

+

 Version 2.2.0 - March, 2017

 ---------------------------

 - Bumped minor version number to reflect compatibility issues with

diff --git a/pyparsing.py b/pyparsing.py
index 532bc85..cf75e1e 100644
--- a/pyparsing.py
+++ b/pyparsing.py
@@ -1,6 +1,6 @@
 # module pyparsing.py

 #

-# Copyright (c) 2003-2016  Paul T. McGuire

+# Copyright (c) 2003-2018  Paul T. McGuire

 #

 # Permission is hereby granted, free of charge, to any person obtaining

 # a copy of this software and associated documentation files (the

@@ -25,6 +25,7 @@
 __doc__ = \

 """

 pyparsing module - Classes and methods to define and execute parsing grammars

+=============================================================================

 

 The pyparsing module is an alternative approach to creating and executing simple grammars,

 vs. the traditional lex/yacc approach, or the use of regular expressions.  With pyparsing, you

@@ -58,10 +59,23 @@ The pyparsing module handles some of the problems that are typically vexing when
  - extra or missing whitespace (the above program will also handle "Hello,World!", "Hello  ,  World  !", etc.)

  - quoted strings

  - embedded comments

+

+

+Getting Started -

+-----------------

+Visit the classes L{ParserElement} and L{ParseResults} to see the base classes that most other pyparsing

+classes inherit from. Use the docstrings for examples of how to:

+ - construct literal match expressions from L{Literal} and L{CaselessLiteral} classes

+ - construct character word-group expressions using the L{Word} class

+ - see how to create repetitive expressions using L{ZeroOrMore} and L{OneOrMore} classes

+ - use L{'+'<And>}, L{'|'<MatchFirst>}, L{'^'<Or>}, and L{'&'<Each>} operators to combine simple expressions into more complex ones

+ - associate names with your parsed results using L{ParserElement.setResultsName}

+ - find some helpful expression short-cuts like L{delimitedList} and L{oneOf}

+ - find more useful common expressions in the L{pyparsing_common} namespace class

 """

 

-__version__ = "2.2.0"

-__versionTime__ = "06 Mar 2017 02:06 UTC"

+__version__ = "2.2.1"

+__versionTime__ = "18 Sep 2018 00:49 UTC"

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

 

 import string

@@ -1034,11 +1048,11 @@ def _trim_arity(func, maxargs=2):
             # special handling for Python 3.5.0 - extra deep call stack by 1

             offset = -3 if system_version == (3,5,0) else -2

             frame_summary = traceback.extract_stack(limit=-offset+limit-1)[offset]

-            return [(frame_summary.filename, frame_summary.lineno)]

+            return [frame_summary[:2]]

         def extract_tb(tb, limit=0):

             frames = traceback.extract_tb(tb, limit=limit)

             frame_summary = frames[-1]

-            return [(frame_summary.filename, frame_summary.lineno)]

+            return [frame_summary[:2]]

     else:

         extract_stack = traceback.extract_stack

         extract_tb = traceback.extract_tb

@@ -1383,7 +1397,7 @@ class ParserElement(object):
             else:

                 preloc = loc

             tokensStart = preloc

-            if self.mayIndexError or loc >= len(instring):

+            if self.mayIndexError or preloc >= len(instring):

                 try:

                     loc,tokens = self.parseImpl( instring, preloc, doActions )

                 except IndexError:

@@ -1417,7 +1431,6 @@ class ParserElement(object):
                                                   self.resultsName,

                                                   asList=self.saveAsList and isinstance(tokens,(ParseResults,list)),

                                                   modal=self.modalResults )

-

         if debugging:

             #~ print ("Matched",self,"->",retTokens.asList())

             if (self.debugActions[1] ):

@@ -4402,7 +4415,7 @@ def traceParseAction(f):
 

         @traceParseAction

         def remove_duplicate_chars(tokens):

-            return ''.join(sorted(set(''.join(tokens)))

+            return ''.join(sorted(set(''.join(tokens))))

 

         wds = OneOrMore(wd).setParseAction(remove_duplicate_chars)

         print(wds.parseString("slkdjs sld sldd sdlf sdljf"))

diff --git a/unitTests.py b/unitTests.py
index 2bc7da7..a31bf40 100644
--- a/unitTests.py
+++ b/unitTests.py
@@ -4,7 +4,7 @@
 #

 # Unit tests for pyparsing module

 #

-# Copyright 2002-2016, Paul McGuire

+# Copyright 2002-2018, Paul McGuire

 #

 #

 from unittest import TestCase, TestSuite, TextTestRunner

@@ -3395,6 +3395,19 @@ class ColTest(ParseTestCase):
         print_(initials)

         assert len(initials) == 4 and all(c=='*' for c in initials), 'fail col test'

 

+class LiteralExceptionTest(ParseTestCase):

+    def runTest(self):

+        import pyparsing as pp

+

+        for cls in (pp.Literal, pp.CaselessLiteral, pp.Keyword, pp.CaselessKeyword,

+             pp.Word, pp.Regex):

+            expr = cls('xyz')#.setName('{}_expr'.format(cls.__name__.lower()))

+

+            try:

+                expr.parseString(' ')

+            except Exception as e:

+                print(cls.__name__, str(e))

+                assert isinstance(e, pp.ParseBaseException), "class {} raised wrong exception type {}".format(cls.__name__, type(e).__name__)

 

 class MiscellaneousParserTests(ParseTestCase):

     def runTest(self):