Commits

Jonathan Eunice committed 1052440

doc tweaks

  • Participants
  • Parent commits 7a7a322

Comments (0)

Files changed (2)

 A simplified interface to Python's regular expression (``re``)
-string search. As a bonus, also provides compatible way to
+string search that tries to eliminate steps and provide
+simpler access to results. As a bonus, also provides compatible way to
 access Unix glob searches.
 
 Usage
 
 Python regular expressions are powerful, but the language's lack of an *en passant*
 assignment requires a preparatory
-motion and then a test, like this::
+motion and then a test::
 
     import re
     
     if some_string in Re(pattern):
         print Re._[1]
         
-There are two things to note here: First,
-this turns the sense of the matching around, asking "is the given string *in*
+This turns the sense of the matching around, asking "is the given string *in*
 the set of items this pattern describes?" To be fancy, the
 ``Re`` pattern is an intensionally
 defined set (namely "all strings matching the pattern"). This order often makes
 given string within the set of *all legitimate commands*?"
 
 Second, the ``in`` test had the side effect of setting the underscore
-name ``_`` to the result. Python doesn't support *en passant* assignment, so
+name ``_`` to the result. Python doesn't support *en passant* assignment--apparently,
+no matter how hard you try, or how much introspection you use. Thus
 you can't both test and collect results in the same motion, even though that's
-sometimes exactly appropriate. 
+often exactly appropriate. Collecting them in a class variable is a fallback.
 
-If you prefer the more traditional ``re`` calls, you can still use them with the
-convenient *en passant* style.::
+If you prefer the more traditional ``re`` calls::
 
     if Re(pattern).search(some_string):
         print Re._[1]
 
-``Re`` works even better with named pattern components, such as::
+``Re`` works even better with named pattern components, which are exposed
+as attributes of the returned object::
 
     person = 'John Smith 48'
     if person in Re(r'(?P<name>[\w\s]*)\s+(?P<age>\d+)'):
     else:
         print "don't understand '{}'".format(person)
         
+One trick being used here is that the returned object is not a pure
+``_sre.SRE_Match`` that Python's ``re`` module returns. Nor is it a subclass.
+(That class `appears to be unsubclassable
+    <http://stackoverflow.com/questions/4835352/subclassing-matchobject-in-python>`_).
+Thus, regular expression matches return a proxy object that
+exposes the match object's numeric (positional) and
+named groups through indices and attributes. If a named group has the same
+name as a match object method or property, it takes precedence. Either
+change the name of the match group or access the underlying property thus:
+``x._match.property``
+        
 It's possible also to loop over the results::
 
     for found in Re('pattern (\w+)').finditer('pattern is as pattern does'):
     else:
         raise ValueError('YES IT IS')
 
-
 Notes
 =====
-
- *  ``simplere`` is part of a larger (as yet unpublished) effort to add intensional sets to Python.
+   
+ *  Automated multi-version testing is managed with the wonderful
+    `pytest <http://pypi.python.org/pypi/pytest>`_
+    and `tox <http://pypi.python.org/pypi/tox>`_. ``simplere`` is
+    successfully packaged for, and tested against, all late-model verions of
+    Python: 2.6, 2.7, 3.2, and 3.3, as well as PyPy 1.9 (based on 2.7.2).
+ 
+ *  ``simplere`` is one part of a larger effort to add intensional sets
+    to Python. The `intensional <http://pypi.python.org/pypi/intensional>`_
+    package contains a parallel implementation of ``Re``, among many other
+    things.
+ 
+ *  The author, `Jonathan Eunice <mailto:jonathan.eunice@gmail.com>`_ or
+    `@jeunice on Twitter <http://twitter.com/jeunice>`_
+    welcomes your comments and suggestions.
 
 Installation
 ============
 
-::
+To install the latest version::
 
     pip install -U simplere
+
+To ``easy_install`` under a specific Python version (3.3 in this example)::
+
+    python3.3 -m easy_install --upgrade simplere
     
-(You may need to prefix this with "sudo " to authorize installation.)
+(You may need to prefix these with "sudo " to authorize installation.)

File simplere/core.py

     _ = None
 
     def __init__(self, pattern, flags=0):
-        self.pattern = pattern
-        self.flags   = flags
-        self.re = re.compile(pattern, flags)
+        self.pattern    = pattern
+        self.flags      = flags
+        self.re         = re.compile(pattern, flags)
         self.groups     = self.re.groups
         self.groupindex = self.re.groupindex
-        self._       = None
         
     def _regroup(self, m):
         """