1. Jonathan Eunice
  2. simplere

Commits

Jonathan Eunice  committed 66e2c16

Doc improvements.

  • Participants
  • Parent commits 36749aa
  • Branches default

Comments (0)

Files changed (13)

File CHANGES.rst

View file
  • Ignore whitespace
 
+1.0.5
+=====
+
+  * In several dot-releases, have added support for Travis-CI 
+    cloud-based continuous integration testing, Sphinx-based 
+    documentation, and readthedocs.org hosted documentation.
+    The Travis bit has required a separate Github repository
+    be created. It is managed out of the same development
+    directory, overlaying the existing Mercurial / Bitbucket
+    repo. So far, that has caused no problems.
+
+  * Documentation somewhat improved.
 
 
 1.0

File README.rst

View file
  • Ignore whitespace
     if match / re.search(pattern, some_string):
         print match[1]
 
-Or with an object-orented style::
+That's particularly valuable in complex search-and-manipulate
+code that requires multiple levels of searching along with
+pre-conditions, error checking, and post-match cleanup, formatting,
+and actions.
 
-    if some_string in Re(pattern):
-        print Re._[1]
-
-
-Re Objects
-==========
-
-``Re`` objects are `memoized
-<http://en.wikipedia.org/wiki/Memoization>`_ for efficiency, so they compile their
-pattern just once, regardless of how many times they're mentioned in a
-program.
-
-Note that the ``in`` test turns the sense of the matching around (compared to
-the standard ``re`` module). It asks "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
-excellent sense whey you have a clear intent for the test. For example, "is the
-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--apparently,
-no matter how hard you try, or how much introspection you use. This makes it
-harder to both test and collect results in the same motion, even though that's
-often exactly appropriate. Collecting them in a class variable is a fallback
-strategy (see the *En Passant* section below for a slicker one).
-
-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, 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+)'):
-        print Re._.name, "is", Re._.age, "years old"
-    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'):
-        print found[1]
-        
-Or collect them all in one fell swoop::
-
-    found = Re('pattern (\w+)').findall('pattern is as pattern does')
-    
-Pretty much all of the methods and properties one can access from the standard
-``re`` module are available.
-
-Bonus: Globs
-============
-
-Regular expressions are wonderfuly powerful, but sometimes the simpler `Unix glob
-<http://en.wikipedia.org/wiki/Glob_(programming)>`_ is works just fine. As a bonus,
+As a bonus,
 ``simplere`` also provides simple glob access.::
 
     if 'globtastic' in Glob('glob*'):
         print "Yes! It is!"
     else:
-        raise ValueError('YES IT IS')
+        raise ValueError('OH YES IT IS!')
 
-En Passant
-==========
-
-If you have existing code that already uses ``re`` regular expressions
-and you want to ease into using ``simplere``, ``ReMatch`` objects can
-simply wrap Python's native``_sre.SRE_Match`` objects (the things that ``re``
-method calls return).::
-
-    match = re.match(r'(?P<word>th.s)', 'this is a string')
-    match = ReMatch(match)
-    if match:
-        print match.group(1)    # still works
-        print match[1]          # same thing
-        print match.word        # same thing, with logical name
-        
-But that's a huge amount of boiler plate for a simple test, right? So ``simplere``
-also uses an *en passant* trick of redefining the division operation::
-    
-    if match / re.search(r'(?P<word>th.s)', 'this is a string'):
-        assert match[1] == 'this'
-        assert match.word == 'this'
-        assert match.group(1) == 'this'
-
-This uses the pre-delcared ``match`` object and the division operator (``/``)
-to quickly funnel
-the result of the search. 
-If the ``re`` operation fails, the resulting object is guaranteed to have
-a ``False``-like boolean value, so that it will fall through conditional tests. 
-
-If you prefer the look of the less-than (``<``) or less-than-or-equal (``<=``),
-as indicators that ``match`` takes the value of the following function call, they
-are supported as aliases of the division operation (``/``). You may define your
-own match objects, and can use them on memoized ``Re`` objects too. Putting
-a few of these optional things together::
-
-    answer = Match()   # need to do this just once
-    
-    if answer < Re(r'(?P<word>th..)').search('and that goes there'):
-        assert answer.word == 'that'
-
-Notes
-=====
-   
- *  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 these with "sudo " to authorize installation.)
+See `Read the Docs <http://simplere.readthedocs.org/en/latest/>`_
+for the full installation and usage documentation.

File docs/README.rst

  • Ignore whitespace
-.. image:: https://travis-ci.org/jonathaneunice/simplere.png?branch=master
-    :target: https://travis-ci.org/jonathaneunice/simplere
-
-.. image:: https://pypip.in/d/simplere/badge.png
-    :target: https://crate.io/packages/simplere/
-
-A simplified interface to Python's regular expression (``re``)
-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* (in passing) assignment requires a preparatory
-motion and then a test::
-
-    import re
-    
-    match = re.search(pattern, some_string)
-    if match:
-        print match.group(1)
-
-With ``simplere``, you can do it in fewer steps::
-
-    from simplere import *
-
-    if match / re.search(pattern, some_string):
-        print match[1]
-
-Or with an object-orented style::
-
-    if some_string in Re(pattern):
-        print Re._[1]
-
-
-Re Objects
-==========
-
-``Re`` objects are `memoized
-<http://en.wikipedia.org/wiki/Memoization>`_ for efficiency, so they compile their
-pattern just once, regardless of how many times they're mentioned in a
-program.
-
-Note that the ``in`` test turns the sense of the matching around (compared to
-the standard ``re`` module). It asks "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
-excellent sense whey you have a clear intent for the test. For example, "is the
-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--apparently,
-no matter how hard you try, or how much introspection you use. This makes it
-harder to both test and collect results in the same motion, even though that's
-often exactly appropriate. Collecting them in a class variable is a fallback
-strategy (see the *En Passant* section below for a slicker one).
-
-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, 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+)'):
-        print Re._.name, "is", Re._.age, "years old"
-    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'):
-        print found[1]
-        
-Or collect them all in one fell swoop::
-
-    found = Re('pattern (\w+)').findall('pattern is as pattern does')
-    
-Pretty much all of the methods and properties one can access from the standard
-``re`` module are available.
-
-Bonus: Globs
-============
-
-Regular expressions are wonderfuly powerful, but sometimes the simpler `Unix glob
-<http://en.wikipedia.org/wiki/Glob_(programming)>`_ is works just fine. As a bonus,
-``simplere`` also provides simple glob access.::
-
-    if 'globtastic' in Glob('glob*'):
-        print "Yes! It is!"
-    else:
-        raise ValueError('YES IT IS')
-
-En Passant
-==========
-
-If you have existing code that already uses ``re`` regular expressions
-and you want to ease into using ``simplere``, ``ReMatch`` objects can
-simply wrap Python's native``_sre.SRE_Match`` objects (the things that ``re``
-method calls return).::
-
-    match = re.match(r'(?P<word>th.s)', 'this is a string')
-    match = ReMatch(match)
-    if match:
-        print match.group(1)    # still works
-        print match[1]          # same thing
-        print match.word        # same thing, with logical name
-        
-But that's a huge amount of boiler plate for a simple test, right? So ``simplere``
-also uses an *en passant* trick of redefining the division operation::
-    
-    if match / re.search(r'(?P<word>th.s)', 'this is a string'):
-        assert match[1] == 'this'
-        assert match.word == 'this'
-        assert match.group(1) == 'this'
-
-This uses the pre-delcared ``match`` object and the division operator (``/``)
-to quickly funnel
-the result of the search. 
-If the ``re`` operation fails, the resulting object is guaranteed to have
-a ``False``-like boolean value, so that it will fall through conditional tests. 
-
-If you prefer the look of the less-than (``<``) or less-than-or-equal (``<=``),
-as indicators that ``match`` takes the value of the following function call, they
-are supported as aliases of the division operation (``/``). You may define your
-own match objects, and can use them on memoized ``Re`` objects too. Putting
-a few of these optional things together::
-
-    answer = Match()   # need to do this just once
-    
-    if answer < Re(r'(?P<word>th..)').search('and that goes there'):
-        assert answer.word == 'that'
-
-Notes
-=====
-   
- *  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 these with "sudo " to authorize installation.)

File docs/_build/doctrees/README.doctree

  • Ignore whitespace
Binary file modified.

File docs/_build/doctrees/environment.pickle

  • Ignore whitespace
Binary file modified.

File docs/_build/doctrees/index.doctree

  • Ignore whitespace
Binary file modified.

File docs/_build/html/README.html

View file
  • Ignore whitespace
     <script type="text/javascript" src="_static/jquery.js"></script>
     <script type="text/javascript" src="_static/underscore.js"></script>
     <script type="text/javascript" src="_static/doctools.js"></script>
-    <link rel="top" title="simplere 1.0.4 documentation" href="index.html" />
-    <link rel="prev" title="Welcome to simplere’s documentation!" href="index.html" /> 
+    <link rel="top" title="simplere 1.0.4 documentation" href="index.html" /> 
   </head>
   <body>
     <div class="related">
         <li class="right" style="margin-right: 10px">
           <a href="genindex.html" title="General Index"
              accesskey="I">index</a></li>
-        <li class="right" >
-          <a href="index.html" title="Welcome to simplere’s documentation!"
-             accesskey="P">previous</a> |</li>
         <li><a href="index.html">simplere 1.0.4 documentation</a> &raquo;</li> 
       </ul>
     </div>  
     <span class="k">print</span> <span class="n">match</span><span class="p">[</span><span class="mi">1</span><span class="p">]</span>
 </pre></div>
 </div>
-<p>Or with an object-orented style:</p>
-<div class="highlight-python"><div class="highlight"><pre><span class="k">if</span> <span class="n">some_string</span> <span class="ow">in</span> <span class="n">Re</span><span class="p">(</span><span class="n">pattern</span><span class="p">):</span>
-    <span class="k">print</span> <span class="n">Re</span><span class="o">.</span><span class="n">_</span><span class="p">[</span><span class="mi">1</span><span class="p">]</span>
-</pre></div>
-</div>
-</div>
-<div class="section" id="re-objects">
-<h1>Re Objects<a class="headerlink" href="#re-objects" title="Permalink to this headline">¶</a></h1>
-<p><tt class="docutils literal"><span class="pre">Re</span></tt> objects are <a class="reference external" href="http://en.wikipedia.org/wiki/Memoization">memoized</a> for efficiency, so they compile their
-pattern just once, regardless of how many times they&#8217;re mentioned in a
-program.</p>
-<p>Note that the <tt class="docutils literal"><span class="pre">in</span></tt> test turns the sense of the matching around (compared to
-the standard <tt class="docutils literal"><span class="pre">re</span></tt> module). It asks &#8220;is the given string <em>in</em>
-the set of items this pattern describes?&#8221; To be fancy, the
-<tt class="docutils literal"><span class="pre">Re</span></tt> pattern is an intensionally
-defined set (namely &#8220;all strings matching the pattern&#8221;). This order often makes
-excellent sense whey you have a clear intent for the test. For example, &#8220;is the
-given string within the set of <em>all legitimate commands</em>?&#8221;</p>
-<p>Second, the <tt class="docutils literal"><span class="pre">in</span></tt> test had the side effect of setting the underscore
-name <tt class="docutils literal"><span class="pre">_</span></tt> to the result. Python doesn&#8217;t support <em>en passant</em> assignment&#8211;apparently,
-no matter how hard you try, or how much introspection you use. This makes it
-harder to both test and collect results in the same motion, even though that&#8217;s
-often exactly appropriate. Collecting them in a class variable is a fallback
-strategy (see the <em>En Passant</em> section below for a slicker one).</p>
-<p>If you prefer the more traditional <tt class="docutils literal"><span class="pre">re</span></tt> calls:</p>
-<div class="highlight-python"><div class="highlight"><pre><span class="k">if</span> <span class="n">Re</span><span class="p">(</span><span class="n">pattern</span><span class="p">)</span><span class="o">.</span><span class="n">search</span><span class="p">(</span><span class="n">some_string</span><span class="p">):</span>
-    <span class="k">print</span> <span class="n">Re</span><span class="o">.</span><span class="n">_</span><span class="p">[</span><span class="mi">1</span><span class="p">]</span>
-</pre></div>
-</div>
-<p><tt class="docutils literal"><span class="pre">Re</span></tt> works even better with named pattern components, which are exposed
-as attributes of the returned object:</p>
-<div class="highlight-python"><div class="highlight"><pre><span class="n">person</span> <span class="o">=</span> <span class="s">&#39;John Smith 48&#39;</span>
-<span class="k">if</span> <span class="n">person</span> <span class="ow">in</span> <span class="n">Re</span><span class="p">(</span><span class="s">r&#39;(?P&lt;name&gt;[\w\s]*)\s+(?P&lt;age&gt;\d+)&#39;</span><span class="p">):</span>
-    <span class="k">print</span> <span class="n">Re</span><span class="o">.</span><span class="n">_</span><span class="o">.</span><span class="n">name</span><span class="p">,</span> <span class="s">&quot;is&quot;</span><span class="p">,</span> <span class="n">Re</span><span class="o">.</span><span class="n">_</span><span class="o">.</span><span class="n">age</span><span class="p">,</span> <span class="s">&quot;years old&quot;</span>
-<span class="k">else</span><span class="p">:</span>
-    <span class="k">print</span> <span class="s">&quot;don&#39;t understand &#39;{}&#39;&quot;</span><span class="o">.</span><span class="n">format</span><span class="p">(</span><span class="n">person</span><span class="p">)</span>
-</pre></div>
-</div>
-<p>One trick being used here is that the returned object is not a pure
-<tt class="docutils literal"><span class="pre">_sre.SRE_Match</span></tt> that Python&#8217;s <tt class="docutils literal"><span class="pre">re</span></tt> module returns. Nor is it a subclass.
-(That class <a class="reference external" href="http://stackoverflow.com/questions/4835352/subclassing-matchobject-in-python">appears to be unsubclassable</a>.)
-Thus, regular expression matches return a proxy object that
-exposes the match object&#8217;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:
-<tt class="docutils literal"><span class="pre">x._match.property</span></tt></p>
-<p>It&#8217;s possible also to loop over the results:</p>
-<div class="highlight-python"><div class="highlight"><pre><span class="k">for</span> <span class="n">found</span> <span class="ow">in</span> <span class="n">Re</span><span class="p">(</span><span class="s">&#39;pattern (\w+)&#39;</span><span class="p">)</span><span class="o">.</span><span class="n">finditer</span><span class="p">(</span><span class="s">&#39;pattern is as pattern does&#39;</span><span class="p">):</span>
-    <span class="k">print</span> <span class="n">found</span><span class="p">[</span><span class="mi">1</span><span class="p">]</span>
-</pre></div>
-</div>
-<p>Or collect them all in one fell swoop:</p>
-<div class="highlight-python"><div class="highlight"><pre><span class="n">found</span> <span class="o">=</span> <span class="n">Re</span><span class="p">(</span><span class="s">&#39;pattern (\w+)&#39;</span><span class="p">)</span><span class="o">.</span><span class="n">findall</span><span class="p">(</span><span class="s">&#39;pattern is as pattern does&#39;</span><span class="p">)</span>
-</pre></div>
-</div>
-<p>Pretty much all of the methods and properties one can access from the standard
-<tt class="docutils literal"><span class="pre">re</span></tt> module are available.</p>
-</div>
-<div class="section" id="bonus-globs">
-<h1>Bonus: Globs<a class="headerlink" href="#bonus-globs" title="Permalink to this headline">¶</a></h1>
-<p>Regular expressions are wonderfuly powerful, but sometimes the simpler <a class="reference external" href="http://en.wikipedia.org/wiki/Glob_(programming)">Unix glob</a> is works just fine. As a bonus,
+<p>That&#8217;s particularly valuable in complex search-and-manipulate
+code that requires multiple levels of searching along with
+pre-conditions, error checking, and post-match cleanup, formatting,
+and actions.</p>
+<p>As a bonus,
 <tt class="docutils literal"><span class="pre">simplere</span></tt> also provides simple glob access.:</p>
 <div class="highlight-python"><div class="highlight"><pre><span class="k">if</span> <span class="s">&#39;globtastic&#39;</span> <span class="ow">in</span> <span class="n">Glob</span><span class="p">(</span><span class="s">&#39;glob*&#39;</span><span class="p">):</span>
     <span class="k">print</span> <span class="s">&quot;Yes! It is!&quot;</span>
 <span class="k">else</span><span class="p">:</span>
-    <span class="k">raise</span> <span class="ne">ValueError</span><span class="p">(</span><span class="s">&#39;YES IT IS&#39;</span><span class="p">)</span>
+    <span class="k">raise</span> <span class="ne">ValueError</span><span class="p">(</span><span class="s">&#39;OH YES IT IS!&#39;</span><span class="p">)</span>
 </pre></div>
 </div>
-</div>
-<div class="section" id="en-passant">
-<h1>En Passant<a class="headerlink" href="#en-passant" title="Permalink to this headline">¶</a></h1>
-<p>If you have existing code that already uses <tt class="docutils literal"><span class="pre">re</span></tt> regular expressions
-and you want to ease into using <tt class="docutils literal"><span class="pre">simplere</span></tt>, <tt class="docutils literal"><span class="pre">ReMatch</span></tt> objects can
-simply wrap Python&#8217;s native``_sre.SRE_Match`` objects (the things that <tt class="docutils literal"><span class="pre">re</span></tt>
-method calls return).:</p>
-<div class="highlight-python"><div class="highlight"><pre><span class="n">match</span> <span class="o">=</span> <span class="n">re</span><span class="o">.</span><span class="n">match</span><span class="p">(</span><span class="s">r&#39;(?P&lt;word&gt;th.s)&#39;</span><span class="p">,</span> <span class="s">&#39;this is a string&#39;</span><span class="p">)</span>
-<span class="n">match</span> <span class="o">=</span> <span class="n">ReMatch</span><span class="p">(</span><span class="n">match</span><span class="p">)</span>
-<span class="k">if</span> <span class="n">match</span><span class="p">:</span>
-    <span class="k">print</span> <span class="n">match</span><span class="o">.</span><span class="n">group</span><span class="p">(</span><span class="mi">1</span><span class="p">)</span>    <span class="c"># still works</span>
-    <span class="k">print</span> <span class="n">match</span><span class="p">[</span><span class="mi">1</span><span class="p">]</span>          <span class="c"># same thing</span>
-    <span class="k">print</span> <span class="n">match</span><span class="o">.</span><span class="n">word</span>        <span class="c"># same thing, with logical name</span>
-</pre></div>
-</div>
-<p>But that&#8217;s a huge amount of boiler plate for a simple test, right? So <tt class="docutils literal"><span class="pre">simplere</span></tt>
-also uses an <em>en passant</em> trick of redefining the division operation:</p>
-<div class="highlight-python"><div class="highlight"><pre><span class="k">if</span> <span class="n">match</span> <span class="o">/</span> <span class="n">re</span><span class="o">.</span><span class="n">search</span><span class="p">(</span><span class="s">r&#39;(?P&lt;word&gt;th.s)&#39;</span><span class="p">,</span> <span class="s">&#39;this is a string&#39;</span><span class="p">):</span>
-    <span class="k">assert</span> <span class="n">match</span><span class="p">[</span><span class="mi">1</span><span class="p">]</span> <span class="o">==</span> <span class="s">&#39;this&#39;</span>
-    <span class="k">assert</span> <span class="n">match</span><span class="o">.</span><span class="n">word</span> <span class="o">==</span> <span class="s">&#39;this&#39;</span>
-    <span class="k">assert</span> <span class="n">match</span><span class="o">.</span><span class="n">group</span><span class="p">(</span><span class="mi">1</span><span class="p">)</span> <span class="o">==</span> <span class="s">&#39;this&#39;</span>
-</pre></div>
-</div>
-<p>This uses the pre-delcared <tt class="docutils literal"><span class="pre">match</span></tt> object and the division operator (<tt class="docutils literal"><span class="pre">/</span></tt>)
-to quickly funnel
-the result of the search.
-If the <tt class="docutils literal"><span class="pre">re</span></tt> operation fails, the resulting object is guaranteed to have
-a <tt class="docutils literal"><span class="pre">False</span></tt>-like boolean value, so that it will fall through conditional tests.</p>
-<p>If you prefer the look of the less-than (<tt class="docutils literal"><span class="pre">&lt;</span></tt>) or less-than-or-equal (<tt class="docutils literal"><span class="pre">&lt;=</span></tt>),
-as indicators that <tt class="docutils literal"><span class="pre">match</span></tt> takes the value of the following function call, they
-are supported as aliases of the division operation (<tt class="docutils literal"><span class="pre">/</span></tt>). You may define your
-own match objects, and can use them on memoized <tt class="docutils literal"><span class="pre">Re</span></tt> objects too. Putting
-a few of these optional things together:</p>
-<div class="highlight-python"><div class="highlight"><pre><span class="n">answer</span> <span class="o">=</span> <span class="n">Match</span><span class="p">()</span>   <span class="c"># need to do this just once</span>
-
-<span class="k">if</span> <span class="n">answer</span> <span class="o">&lt;</span> <span class="n">Re</span><span class="p">(</span><span class="s">r&#39;(?P&lt;word&gt;th..)&#39;</span><span class="p">)</span><span class="o">.</span><span class="n">search</span><span class="p">(</span><span class="s">&#39;and that goes there&#39;</span><span class="p">):</span>
-    <span class="k">assert</span> <span class="n">answer</span><span class="o">.</span><span class="n">word</span> <span class="o">==</span> <span class="s">&#39;that&#39;</span>
-</pre></div>
-</div>
-</div>
-<div class="section" id="notes">
-<h1>Notes<a class="headerlink" href="#notes" title="Permalink to this headline">¶</a></h1>
-<blockquote>
-<div><ul class="simple">
-<li>Automated multi-version testing is managed with the wonderful
-<a class="reference external" href="http://pypi.python.org/pypi/pytest">pytest</a>
-and <a class="reference external" href="http://pypi.python.org/pypi/tox">tox</a>. <tt class="docutils literal"><span class="pre">simplere</span></tt> 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).</li>
-<li><tt class="docutils literal"><span class="pre">simplere</span></tt> is one part of a larger effort to add intensional sets
-to Python. The <a class="reference external" href="http://pypi.python.org/pypi/intensional">intensional</a>
-package contains a parallel implementation of <tt class="docutils literal"><span class="pre">Re</span></tt>, among many other
-things.</li>
-<li>The author, <a class="reference external" href="mailto:jonathan&#46;eunice&#37;&#52;&#48;gmail&#46;com">Jonathan Eunice</a> or
-<a class="reference external" href="http://twitter.com/jeunice">&#64;jeunice on Twitter</a>
-welcomes your comments and suggestions.</li>
-</ul>
-</div></blockquote>
-</div>
-<div class="section" id="installation">
-<h1>Installation<a class="headerlink" href="#installation" title="Permalink to this headline">¶</a></h1>
-<p>To install the latest version:</p>
-<div class="highlight-python"><pre>pip install -U simplere</pre>
-</div>
-<p>To <tt class="docutils literal"><span class="pre">easy_install</span></tt> under a specific Python version (3.3 in this example):</p>
-<div class="highlight-python"><pre>python3.3 -m easy_install --upgrade simplere</pre>
-</div>
-<p>(You may need to prefix these with &#8220;sudo &#8221; to authorize installation.)</p>
+<p>See <a class="reference external" href="http://simplere.readthedocs.org/en/latest/">Read the Docs</a>
+for the full installation and usage documentation.</p>
 </div>
 
 
       </div>
       <div class="sphinxsidebar">
         <div class="sphinxsidebarwrapper">
-  <h3><a href="index.html">Table Of Contents</a></h3>
-  <ul>
-<li><a class="reference internal" href="#">Usage</a></li>
-<li><a class="reference internal" href="#re-objects">Re Objects</a></li>
-<li><a class="reference internal" href="#bonus-globs">Bonus: Globs</a></li>
-<li><a class="reference internal" href="#en-passant">En Passant</a></li>
-<li><a class="reference internal" href="#notes">Notes</a></li>
-<li><a class="reference internal" href="#installation">Installation</a></li>
-</ul>
-
-  <h4>Previous topic</h4>
-  <p class="topless"><a href="index.html"
-                        title="previous chapter">Welcome to simplere&#8217;s documentation!</a></p>
   <h3>This Page</h3>
   <ul class="this-page-menu">
     <li><a href="_sources/README.txt"
         <li class="right" style="margin-right: 10px">
           <a href="genindex.html" title="General Index"
              >index</a></li>
-        <li class="right" >
-          <a href="index.html" title="Welcome to simplere’s documentation!"
-             >previous</a> |</li>
         <li><a href="index.html">simplere 1.0.4 documentation</a> &raquo;</li> 
       </ul>
     </div>

File docs/_build/html/_sources/README.txt

View file
  • Ignore whitespace
     if match / re.search(pattern, some_string):
         print match[1]
 
-Or with an object-orented style::
+That's particularly valuable in complex search-and-manipulate
+code that requires multiple levels of searching along with
+pre-conditions, error checking, and post-match cleanup, formatting,
+and actions.
 
-    if some_string in Re(pattern):
-        print Re._[1]
-
-
-Re Objects
-==========
-
-``Re`` objects are `memoized
-<http://en.wikipedia.org/wiki/Memoization>`_ for efficiency, so they compile their
-pattern just once, regardless of how many times they're mentioned in a
-program.
-
-Note that the ``in`` test turns the sense of the matching around (compared to
-the standard ``re`` module). It asks "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
-excellent sense whey you have a clear intent for the test. For example, "is the
-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--apparently,
-no matter how hard you try, or how much introspection you use. This makes it
-harder to both test and collect results in the same motion, even though that's
-often exactly appropriate. Collecting them in a class variable is a fallback
-strategy (see the *En Passant* section below for a slicker one).
-
-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, 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+)'):
-        print Re._.name, "is", Re._.age, "years old"
-    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'):
-        print found[1]
-        
-Or collect them all in one fell swoop::
-
-    found = Re('pattern (\w+)').findall('pattern is as pattern does')
-    
-Pretty much all of the methods and properties one can access from the standard
-``re`` module are available.
-
-Bonus: Globs
-============
-
-Regular expressions are wonderfuly powerful, but sometimes the simpler `Unix glob
-<http://en.wikipedia.org/wiki/Glob_(programming)>`_ is works just fine. As a bonus,
+As a bonus,
 ``simplere`` also provides simple glob access.::
 
     if 'globtastic' in Glob('glob*'):
         print "Yes! It is!"
     else:
-        raise ValueError('YES IT IS')
+        raise ValueError('OH YES IT IS!')
 
-En Passant
-==========
-
-If you have existing code that already uses ``re`` regular expressions
-and you want to ease into using ``simplere``, ``ReMatch`` objects can
-simply wrap Python's native``_sre.SRE_Match`` objects (the things that ``re``
-method calls return).::
-
-    match = re.match(r'(?P<word>th.s)', 'this is a string')
-    match = ReMatch(match)
-    if match:
-        print match.group(1)    # still works
-        print match[1]          # same thing
-        print match.word        # same thing, with logical name
-        
-But that's a huge amount of boiler plate for a simple test, right? So ``simplere``
-also uses an *en passant* trick of redefining the division operation::
-    
-    if match / re.search(r'(?P<word>th.s)', 'this is a string'):
-        assert match[1] == 'this'
-        assert match.word == 'this'
-        assert match.group(1) == 'this'
-
-This uses the pre-delcared ``match`` object and the division operator (``/``)
-to quickly funnel
-the result of the search. 
-If the ``re`` operation fails, the resulting object is guaranteed to have
-a ``False``-like boolean value, so that it will fall through conditional tests. 
-
-If you prefer the look of the less-than (``<``) or less-than-or-equal (``<=``),
-as indicators that ``match`` takes the value of the following function call, they
-are supported as aliases of the division operation (``/``). You may define your
-own match objects, and can use them on memoized ``Re`` objects too. Putting
-a few of these optional things together::
-
-    answer = Match()   # need to do this just once
-    
-    if answer < Re(r'(?P<word>th..)').search('and that goes there'):
-        assert answer.word == 'that'
-
-Notes
-=====
-   
- *  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 these with "sudo " to authorize installation.)
+See `Read the Docs <http://simplere.readthedocs.org/en/latest/>`_
+for the full installation and usage documentation.

File docs/_build/html/_sources/index.txt

View file
  • Ignore whitespace
-.. simplere documentation master file, created by
-   sphinx-quickstart on Fri Sep 13 13:54:51 2013.
-   You can adapt this file completely to your liking, but it should at least
-   contain the root `toctree` directive.
+simplere
+========
 
-Welcome to simplere's documentation!
-====================================
+A simplified interface to Python's regular expression (``re``)
+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.
 
-Contents:
+Usage
+=====
+
+Python regular expressions are powerful, but the language's lack
+of an *en passant* (in passing) assignment requires a preparatory
+motion and then a test::
+
+    import re
+
+    match = re.search(pattern, some_string)
+    if match:
+        print match.group(1)
+
+With ``simplere``, you can do it in fewer steps::
+
+    from simplere import *
+
+    if match / re.search(pattern, some_string):
+        print match[1]
+
+Motivation
+==========
+
+In the simple examples above, "fewer steps" seems like a small
+savings (3 lines to 2). While a 33% savings is a pretty good
+optimization, is it really worth using another module and
+a quirky *en passant* operator to get it?
+
+In code this simple, maybe not. But real regex-based searching tends
+to have multiple, cascading searches, and to be tightly interwoven
+with complex pre-conditions, error-checking, and post-match formatting
+or actions. It gets complicated fast. When multiple ``re`` matches
+must be done, it consumes a lot of "vertical space" and often
+threatens to push the number of lines a programmer is viewing at
+any given moment beyond the number that can be easily held in working
+memory. In that case, it proves valuable to condense what is logically
+a single operation ("regular expression test") into a single line
+with its conditional ``if``.
+
+This is even more true for the "exploratory" phases of development,
+before a program's appropriate structure and best logical boundaries
+have been established.  One can always "back out" the condensing *en
+passant* operation in later production code, if desired.
 
 .. toctree::
    :maxdepth: 2
 
+Re Objects
+==========
 
-   README
+``Re`` objects are `memoized
+<http://en.wikipedia.org/wiki/Memoization>`_ for efficiency, so they compile their
+pattern just once, regardless of how many times they're mentioned in a
+program.
 
+Note that the ``in`` test turns the sense of the matching around (compared to
+the standard ``re`` module). It asks "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
+excellent sense whey you have a clear intent for the test. For example, "is the
+given string within the set of *all legitimate commands*?"
 
-Indices and tables
-==================
+Second, the ``in`` test had the side effect of setting the underscore
+name ``_`` to the result. Python doesn't support *en passant* assignment--apparently,
+no matter how hard you try, or how much introspection you use. This makes it
+harder to both test and collect results in the same motion, even though that's
+often exactly appropriate. Collecting them in a class variable is a fallback
+strategy (see the *En Passant* section below for a slicker one).
 
-* :ref:`genindex`
-* :ref:`modindex`
-* :ref:`search`
+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, 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+)'):
+        print Re._.name, "is", Re._.age, "years old"
+    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'):
+        print found[1]
+
+Or collect them all in one fell swoop::
+
+    found = Re('pattern (\w+)').findall('pattern is as pattern does')
+
+Pretty much all of the methods and properties one can access from the standard
+``re`` module are available.
+
+Bonus: Globs
+============
+
+Regular expressions are wonderfully powerful, but sometimes the simpler `Unix glob
+<http://en.wikipedia.org/wiki/Glob_(programming)>`_ is works just fine. As a bonus,
+``simplere`` also provides simple glob access.::
+
+    if 'globtastic' in Glob('glob*'):
+        print "Yes! It is!"
+    else:
+        raise ValueError('YES IT IS')
+
+En Passant, Under the Covers
+============================
+
+``ReMatch`` objects
+wrap Python's native``_sre.SRE_Match`` objects (the things that ``re``
+method calls return).::
+
+    match = re.match(r'(?P<word>th.s)', 'this is a string')
+    match = ReMatch(match)
+    if match:
+        print match.group(1)    # still works
+        print match[1]          # same thing
+        print match.word        # same thing, with logical name
+
+But that's a huge amount of boiler plate for a simple test, right? So ``simplere``
+*en passant* operator redefining the division operation and proxies the ``re`` result
+on the fly to the pre-defined ``match`` object::
+
+    if match / re.search(r'(?P<word>th.s)', 'this is a string'):
+        assert match[1] == 'this'
+        assert match.word == 'this'
+        assert match.group(1) == 'this'
+
+If the ``re`` operation fails, the resulting object is guaranteed to have
+a ``False``-like Boolean value, so that it will fall through conditional tests.
+
+If you prefer the look of the less-than (``<``) or less-than-or-equal (``<=``),
+as indicators that ``match`` takes the value of the following function call, they
+are experimentally supported as aliases of the division operation (``/``).
+You may define your
+own match objects, and can use them on memoized ``Re`` objects too. Putting
+a few of these optional things together::
+
+    answer = Match()   # need to do this just once
+
+    if answer < Re(r'(?P<word>th..)').search('and that goes there'):
+        assert answer.word == 'that'
+
+Notes
+=====
+
+ *  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 versions of
+    Python: 2.6, 2.7, 3.2, and 3.3, as well as PyPy 2.1 (based on 2.7.3).
+    Travis-CI testing has also commenced.
+
+ *  ``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 these with "sudo " to authorize installation.)

File docs/_build/html/index.html

View file
  • Ignore whitespace
   <head>
     <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
     
-    <title>Welcome to simplere’s documentation! &mdash; simplere 1.0.4 documentation</title>
+    <title>simplere &mdash; simplere 1.0.4 documentation</title>
     
     <link rel="stylesheet" href="_static/default.css" type="text/css" />
     <link rel="stylesheet" href="_static/pygments.css" type="text/css" />
     <script type="text/javascript" src="_static/jquery.js"></script>
     <script type="text/javascript" src="_static/underscore.js"></script>
     <script type="text/javascript" src="_static/doctools.js"></script>
-    <link rel="top" title="simplere 1.0.4 documentation" href="#" />
-    <link rel="next" title="Usage" href="README.html" /> 
+    <link rel="top" title="simplere 1.0.4 documentation" href="#" /> 
   </head>
   <body>
     <div class="related">
         <li class="right" style="margin-right: 10px">
           <a href="genindex.html" title="General Index"
              accesskey="I">index</a></li>
-        <li class="right" >
-          <a href="README.html" title="Usage"
-             accesskey="N">next</a> |</li>
         <li><a href="#">simplere 1.0.4 documentation</a> &raquo;</li> 
       </ul>
     </div>  
         <div class="bodywrapper">
           <div class="body">
             
-  <div class="section" id="welcome-to-simplere-s-documentation">
-<h1>Welcome to simplere&#8217;s documentation!<a class="headerlink" href="#welcome-to-simplere-s-documentation" title="Permalink to this headline">¶</a></h1>
-<p>Contents:</p>
+  <div class="section" id="simplere">
+<h1>simplere<a class="headerlink" href="#simplere" title="Permalink to this headline">¶</a></h1>
+<p>A simplified interface to Python&#8217;s regular expression (<tt class="docutils literal"><span class="pre">re</span></tt>)
+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.</p>
+</div>
+<div class="section" id="usage">
+<h1>Usage<a class="headerlink" href="#usage" title="Permalink to this headline">¶</a></h1>
+<p>Python regular expressions are powerful, but the language&#8217;s lack
+of an <em>en passant</em> (in passing) assignment requires a preparatory
+motion and then a test:</p>
+<div class="highlight-python"><div class="highlight"><pre><span class="kn">import</span> <span class="nn">re</span>
+
+<span class="n">match</span> <span class="o">=</span> <span class="n">re</span><span class="o">.</span><span class="n">search</span><span class="p">(</span><span class="n">pattern</span><span class="p">,</span> <span class="n">some_string</span><span class="p">)</span>
+<span class="k">if</span> <span class="n">match</span><span class="p">:</span>
+    <span class="k">print</span> <span class="n">match</span><span class="o">.</span><span class="n">group</span><span class="p">(</span><span class="mi">1</span><span class="p">)</span>
+</pre></div>
+</div>
+<p>With <tt class="docutils literal"><span class="pre">simplere</span></tt>, you can do it in fewer steps:</p>
+<div class="highlight-python"><div class="highlight"><pre><span class="kn">from</span> <span class="nn">simplere</span> <span class="kn">import</span> <span class="o">*</span>
+
+<span class="k">if</span> <span class="n">match</span> <span class="o">/</span> <span class="n">re</span><span class="o">.</span><span class="n">search</span><span class="p">(</span><span class="n">pattern</span><span class="p">,</span> <span class="n">some_string</span><span class="p">):</span>
+    <span class="k">print</span> <span class="n">match</span><span class="p">[</span><span class="mi">1</span><span class="p">]</span>
+</pre></div>
+</div>
+</div>
+<div class="section" id="motivation">
+<h1>Motivation<a class="headerlink" href="#motivation" title="Permalink to this headline">¶</a></h1>
+<p>In the simple examples above, &#8220;fewer steps&#8221; seems like a small
+savings (3 lines to 2). While a 33% savings is a pretty good
+optimization, is it really worth using another module and
+a quirky <em>en passant</em> operator to get it?</p>
+<p>In code this simple, maybe not. But real regex-based searching tends
+to have multiple, cascading searches, and to be tightly interwoven
+with complex pre-conditions, error-checking, and post-match formatting
+or actions. It gets complicated fast. When multiple <tt class="docutils literal"><span class="pre">re</span></tt> matches
+must be done, it consumes a lot of &#8220;vertical space&#8221; and often
+threatens to push the number of lines a programmer is viewing at
+any given moment beyond the number that can be easily held in working
+memory. In that case, it proves valuable to condense what is logically
+a single operation (&#8220;regular expression test&#8221;) into a single line
+with its conditional <tt class="docutils literal"><span class="pre">if</span></tt>.</p>
+<p>This is even more true for the &#8220;exploratory&#8221; phases of development,
+before a program&#8217;s appropriate structure and best logical boundaries
+have been established.  One can always &#8220;back out&#8221; the condensing <em>en
+passant</em> operation in later production code, if desired.</p>
 <div class="toctree-wrapper compound">
-<ul>
-<li class="toctree-l1"><a class="reference internal" href="README.html">Usage</a></li>
-<li class="toctree-l1"><a class="reference internal" href="README.html#re-objects">Re Objects</a></li>
-<li class="toctree-l1"><a class="reference internal" href="README.html#bonus-globs">Bonus: Globs</a></li>
-<li class="toctree-l1"><a class="reference internal" href="README.html#en-passant">En Passant</a></li>
-<li class="toctree-l1"><a class="reference internal" href="README.html#notes">Notes</a></li>
-<li class="toctree-l1"><a class="reference internal" href="README.html#installation">Installation</a></li>
+<ul class="simple">
 </ul>
 </div>
 </div>
-<div class="section" id="indices-and-tables">
-<h1>Indices and tables<a class="headerlink" href="#indices-and-tables" title="Permalink to this headline">¶</a></h1>
-<ul class="simple">
-<li><a class="reference internal" href="genindex.html"><em>Index</em></a></li>
-<li><a class="reference internal" href="py-modindex.html"><em>Module Index</em></a></li>
-<li><a class="reference internal" href="search.html"><em>Search Page</em></a></li>
+<div class="section" id="re-objects">
+<h1>Re Objects<a class="headerlink" href="#re-objects" title="Permalink to this headline">¶</a></h1>
+<p><tt class="docutils literal"><span class="pre">Re</span></tt> objects are <a class="reference external" href="http://en.wikipedia.org/wiki/Memoization">memoized</a> for efficiency, so they compile their
+pattern just once, regardless of how many times they&#8217;re mentioned in a
+program.</p>
+<p>Note that the <tt class="docutils literal"><span class="pre">in</span></tt> test turns the sense of the matching around (compared to
+the standard <tt class="docutils literal"><span class="pre">re</span></tt> module). It asks &#8220;is the given string <em>in</em>
+the set of items this pattern describes?&#8221; To be fancy, the
+<tt class="docutils literal"><span class="pre">Re</span></tt> pattern is an intensionally
+defined set (namely &#8220;all strings matching the pattern&#8221;). This order often makes
+excellent sense whey you have a clear intent for the test. For example, &#8220;is the
+given string within the set of <em>all legitimate commands</em>?&#8221;</p>
+<p>Second, the <tt class="docutils literal"><span class="pre">in</span></tt> test had the side effect of setting the underscore
+name <tt class="docutils literal"><span class="pre">_</span></tt> to the result. Python doesn&#8217;t support <em>en passant</em> assignment&#8211;apparently,
+no matter how hard you try, or how much introspection you use. This makes it
+harder to both test and collect results in the same motion, even though that&#8217;s
+often exactly appropriate. Collecting them in a class variable is a fallback
+strategy (see the <em>En Passant</em> section below for a slicker one).</p>
+<p>If you prefer the more traditional <tt class="docutils literal"><span class="pre">re</span></tt> calls:</p>
+<div class="highlight-python"><div class="highlight"><pre><span class="k">if</span> <span class="n">Re</span><span class="p">(</span><span class="n">pattern</span><span class="p">)</span><span class="o">.</span><span class="n">search</span><span class="p">(</span><span class="n">some_string</span><span class="p">):</span>
+    <span class="k">print</span> <span class="n">Re</span><span class="o">.</span><span class="n">_</span><span class="p">[</span><span class="mi">1</span><span class="p">]</span>
+</pre></div>
+</div>
+<p><tt class="docutils literal"><span class="pre">Re</span></tt> works even better with named pattern components, which are exposed
+as attributes of the returned object:</p>
+<div class="highlight-python"><div class="highlight"><pre><span class="n">person</span> <span class="o">=</span> <span class="s">&#39;John Smith 48&#39;</span>
+<span class="k">if</span> <span class="n">person</span> <span class="ow">in</span> <span class="n">Re</span><span class="p">(</span><span class="s">r&#39;(?P&lt;name&gt;[\w\s]*)\s+(?P&lt;age&gt;\d+)&#39;</span><span class="p">):</span>
+    <span class="k">print</span> <span class="n">Re</span><span class="o">.</span><span class="n">_</span><span class="o">.</span><span class="n">name</span><span class="p">,</span> <span class="s">&quot;is&quot;</span><span class="p">,</span> <span class="n">Re</span><span class="o">.</span><span class="n">_</span><span class="o">.</span><span class="n">age</span><span class="p">,</span> <span class="s">&quot;years old&quot;</span>
+<span class="k">else</span><span class="p">:</span>
+    <span class="k">print</span> <span class="s">&quot;don&#39;t understand &#39;{}&#39;&quot;</span><span class="o">.</span><span class="n">format</span><span class="p">(</span><span class="n">person</span><span class="p">)</span>
+</pre></div>
+</div>
+<p>One trick being used here is that the returned object is not a pure
+<tt class="docutils literal"><span class="pre">_sre.SRE_Match</span></tt> that Python&#8217;s <tt class="docutils literal"><span class="pre">re</span></tt> module returns. Nor is it a subclass.
+(That class <a class="reference external" href="http://stackoverflow.com/questions/4835352/subclassing-matchobject-in-python">appears to be unsubclassable</a>.)
+Thus, regular expression matches return a proxy object that
+exposes the match object&#8217;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:
+<tt class="docutils literal"><span class="pre">x._match.property</span></tt></p>
+<p>It&#8217;s possible also to loop over the results:</p>
+<div class="highlight-python"><div class="highlight"><pre><span class="k">for</span> <span class="n">found</span> <span class="ow">in</span> <span class="n">Re</span><span class="p">(</span><span class="s">&#39;pattern (\w+)&#39;</span><span class="p">)</span><span class="o">.</span><span class="n">finditer</span><span class="p">(</span><span class="s">&#39;pattern is as pattern does&#39;</span><span class="p">):</span>
+    <span class="k">print</span> <span class="n">found</span><span class="p">[</span><span class="mi">1</span><span class="p">]</span>
+</pre></div>
+</div>
+<p>Or collect them all in one fell swoop:</p>
+<div class="highlight-python"><div class="highlight"><pre><span class="n">found</span> <span class="o">=</span> <span class="n">Re</span><span class="p">(</span><span class="s">&#39;pattern (\w+)&#39;</span><span class="p">)</span><span class="o">.</span><span class="n">findall</span><span class="p">(</span><span class="s">&#39;pattern is as pattern does&#39;</span><span class="p">)</span>
+</pre></div>
+</div>
+<p>Pretty much all of the methods and properties one can access from the standard
+<tt class="docutils literal"><span class="pre">re</span></tt> module are available.</p>
+</div>
+<div class="section" id="bonus-globs">
+<h1>Bonus: Globs<a class="headerlink" href="#bonus-globs" title="Permalink to this headline">¶</a></h1>
+<p>Regular expressions are wonderfully powerful, but sometimes the simpler <a class="reference external" href="http://en.wikipedia.org/wiki/Glob_(programming)">Unix glob</a> is works just fine. As a bonus,
+<tt class="docutils literal"><span class="pre">simplere</span></tt> also provides simple glob access.:</p>
+<div class="highlight-python"><div class="highlight"><pre><span class="k">if</span> <span class="s">&#39;globtastic&#39;</span> <span class="ow">in</span> <span class="n">Glob</span><span class="p">(</span><span class="s">&#39;glob*&#39;</span><span class="p">):</span>
+    <span class="k">print</span> <span class="s">&quot;Yes! It is!&quot;</span>
+<span class="k">else</span><span class="p">:</span>
+    <span class="k">raise</span> <span class="ne">ValueError</span><span class="p">(</span><span class="s">&#39;YES IT IS&#39;</span><span class="p">)</span>
+</pre></div>
+</div>
+</div>
+<div class="section" id="en-passant-under-the-covers">
+<h1>En Passant, Under the Covers<a class="headerlink" href="#en-passant-under-the-covers" title="Permalink to this headline">¶</a></h1>
+<p><tt class="docutils literal"><span class="pre">ReMatch</span></tt> objects
+wrap Python&#8217;s native``_sre.SRE_Match`` objects (the things that <tt class="docutils literal"><span class="pre">re</span></tt>
+method calls return).:</p>
+<div class="highlight-python"><div class="highlight"><pre><span class="n">match</span> <span class="o">=</span> <span class="n">re</span><span class="o">.</span><span class="n">match</span><span class="p">(</span><span class="s">r&#39;(?P&lt;word&gt;th.s)&#39;</span><span class="p">,</span> <span class="s">&#39;this is a string&#39;</span><span class="p">)</span>
+<span class="n">match</span> <span class="o">=</span> <span class="n">ReMatch</span><span class="p">(</span><span class="n">match</span><span class="p">)</span>
+<span class="k">if</span> <span class="n">match</span><span class="p">:</span>
+    <span class="k">print</span> <span class="n">match</span><span class="o">.</span><span class="n">group</span><span class="p">(</span><span class="mi">1</span><span class="p">)</span>    <span class="c"># still works</span>
+    <span class="k">print</span> <span class="n">match</span><span class="p">[</span><span class="mi">1</span><span class="p">]</span>          <span class="c"># same thing</span>
+    <span class="k">print</span> <span class="n">match</span><span class="o">.</span><span class="n">word</span>        <span class="c"># same thing, with logical name</span>
+</pre></div>
+</div>
+<p>But that&#8217;s a huge amount of boiler plate for a simple test, right? So <tt class="docutils literal"><span class="pre">simplere</span></tt>
+<em>en passant</em> operator redefining the division operation and proxies the <tt class="docutils literal"><span class="pre">re</span></tt> result
+on the fly to the pre-defined <tt class="docutils literal"><span class="pre">match</span></tt> object:</p>
+<div class="highlight-python"><div class="highlight"><pre><span class="k">if</span> <span class="n">match</span> <span class="o">/</span> <span class="n">re</span><span class="o">.</span><span class="n">search</span><span class="p">(</span><span class="s">r&#39;(?P&lt;word&gt;th.s)&#39;</span><span class="p">,</span> <span class="s">&#39;this is a string&#39;</span><span class="p">):</span>
+    <span class="k">assert</span> <span class="n">match</span><span class="p">[</span><span class="mi">1</span><span class="p">]</span> <span class="o">==</span> <span class="s">&#39;this&#39;</span>
+    <span class="k">assert</span> <span class="n">match</span><span class="o">.</span><span class="n">word</span> <span class="o">==</span> <span class="s">&#39;this&#39;</span>
+    <span class="k">assert</span> <span class="n">match</span><span class="o">.</span><span class="n">group</span><span class="p">(</span><span class="mi">1</span><span class="p">)</span> <span class="o">==</span> <span class="s">&#39;this&#39;</span>
+</pre></div>
+</div>
+<p>If the <tt class="docutils literal"><span class="pre">re</span></tt> operation fails, the resulting object is guaranteed to have
+a <tt class="docutils literal"><span class="pre">False</span></tt>-like Boolean value, so that it will fall through conditional tests.</p>
+<p>If you prefer the look of the less-than (<tt class="docutils literal"><span class="pre">&lt;</span></tt>) or less-than-or-equal (<tt class="docutils literal"><span class="pre">&lt;=</span></tt>),
+as indicators that <tt class="docutils literal"><span class="pre">match</span></tt> takes the value of the following function call, they
+are experimentally supported as aliases of the division operation (<tt class="docutils literal"><span class="pre">/</span></tt>).
+You may define your
+own match objects, and can use them on memoized <tt class="docutils literal"><span class="pre">Re</span></tt> objects too. Putting
+a few of these optional things together:</p>
+<div class="highlight-python"><div class="highlight"><pre><span class="n">answer</span> <span class="o">=</span> <span class="n">Match</span><span class="p">()</span>   <span class="c"># need to do this just once</span>
+
+<span class="k">if</span> <span class="n">answer</span> <span class="o">&lt;</span> <span class="n">Re</span><span class="p">(</span><span class="s">r&#39;(?P&lt;word&gt;th..)&#39;</span><span class="p">)</span><span class="o">.</span><span class="n">search</span><span class="p">(</span><span class="s">&#39;and that goes there&#39;</span><span class="p">):</span>
+    <span class="k">assert</span> <span class="n">answer</span><span class="o">.</span><span class="n">word</span> <span class="o">==</span> <span class="s">&#39;that&#39;</span>
+</pre></div>
+</div>
+</div>
+<div class="section" id="notes">
+<h1>Notes<a class="headerlink" href="#notes" title="Permalink to this headline">¶</a></h1>
+<blockquote>
+<div><ul class="simple">
+<li>Automated multi-version testing is managed with the wonderful
+<a class="reference external" href="http://pypi.python.org/pypi/pytest">pytest</a>
+and <a class="reference external" href="http://pypi.python.org/pypi/tox">tox</a>. <tt class="docutils literal"><span class="pre">simplere</span></tt> is
+successfully packaged for, and tested against, all late-model versions of
+Python: 2.6, 2.7, 3.2, and 3.3, as well as PyPy 2.1 (based on 2.7.3).
+Travis-CI testing has also commenced.</li>
+<li><tt class="docutils literal"><span class="pre">simplere</span></tt> is one part of a larger effort to add intensional sets
+to Python. The <a class="reference external" href="http://pypi.python.org/pypi/intensional">intensional</a>
+package contains a parallel implementation of <tt class="docutils literal"><span class="pre">Re</span></tt>, among many other
+things.</li>
+<li>The author, <a class="reference external" href="mailto:jonathan&#46;eunice&#37;&#52;&#48;gmail&#46;com">Jonathan Eunice</a> or
+<a class="reference external" href="http://twitter.com/jeunice">&#64;jeunice on Twitter</a>
+welcomes your comments and suggestions.</li>
 </ul>
+</div></blockquote>
+</div>
+<div class="section" id="installation">
+<h1>Installation<a class="headerlink" href="#installation" title="Permalink to this headline">¶</a></h1>
+<p>To install the latest version:</p>
+<div class="highlight-python"><pre>pip install -U simplere</pre>
+</div>
+<p>To <tt class="docutils literal"><span class="pre">easy_install</span></tt> under a specific Python version (3.3 in this example):</p>
+<div class="highlight-python"><pre>python3.3 -m easy_install --upgrade simplere</pre>
+</div>
+<p>(You may need to prefix these with &#8220;sudo &#8221; to authorize installation.)</p>
 </div>
 
 
         <div class="sphinxsidebarwrapper">
   <h3><a href="#">Table Of Contents</a></h3>
   <ul>
-<li><a class="reference internal" href="#">Welcome to simplere&#8217;s documentation!</a><ul>
+<li><a class="reference internal" href="#">simplere</a></li>
+<li><a class="reference internal" href="#usage">Usage</a></li>
+<li><a class="reference internal" href="#motivation">Motivation</a><ul>
 </ul>
 </li>
-<li><a class="reference internal" href="#indices-and-tables">Indices and tables</a></li>
+<li><a class="reference internal" href="#re-objects">Re Objects</a></li>
+<li><a class="reference internal" href="#bonus-globs">Bonus: Globs</a></li>
+<li><a class="reference internal" href="#en-passant-under-the-covers">En Passant, Under the Covers</a></li>
+<li><a class="reference internal" href="#notes">Notes</a></li>
+<li><a class="reference internal" href="#installation">Installation</a></li>
 </ul>
 
-  <h4>Next topic</h4>
-  <p class="topless"><a href="README.html"
-                        title="next chapter">Usage</a></p>
   <h3>This Page</h3>
   <ul class="this-page-menu">
     <li><a href="_sources/index.txt"
         <li class="right" style="margin-right: 10px">
           <a href="genindex.html" title="General Index"
              >index</a></li>
-        <li class="right" >
-          <a href="README.html" title="Usage"
-             >next</a> |</li>
         <li><a href="#">simplere 1.0.4 documentation</a> &raquo;</li> 
       </ul>
     </div>

File docs/_build/html/searchindex.js

View file
  • Ignore whitespace
-Search.setIndex({objects:{},terms:{comment:0,all:0,code:0,just:0,less:0,over:0,lack:0,indic:[0,1],prefix:0,through:0,verion:0,follow:0,still:0,fine:0,languag:0,sre_match:0,access:0,style:0,group:0,pretti:0,how:0,had:0,better:0,add:0,program:0,requir:0,"_sre":0,sens:0,eunic:0,match:0,take:0,plate:0,them:0,orent:0,"return":0,around:0,thei:0,format:0,python:0,wai:0,express:0,pypi:0,wonderfuli:0,variabl:0,autom:0,mention:0,alias:0,fall:0,appar:0,preparatori:0,nor:0,like:0,tri:0,slicker:0,name:0,specif:0,fewer:0,"try":0,item:0,alreadi:0,either:0,contain:0,found:0,page:1,compil:0,set:0,old:0,often:0,twitter:0,hard:0,second:0,doe:0,result:0,pass:0,fail:0,guarante:0,successfulli:0,wonder:0,compat:0,index:1,appear:0,compar:0,collect:0,some_str:0,pattern:0,section:0,introspect:0,subclass:0,content:1,version:0,print:0,"import":0,method:0,attribut:0,model:0,elimin:0,object:[0,1],proxi:0,power:0,numer:0,gener:[],even:0,usag:[0,1],tox:0,here:0,standard:0,step:0,base:0,ask:0,valu:0,simpler:[0,1],intension:0,both:0,search:[0,1],expos:0,jeunic:0,larger:0,equal:0,against:0,manag:0,motion:0,thing:0,amount:0,fell:0,pure:0,logic:0,fals:0,mani:0,chang:0,parallel:0,python3:0,bonu:[0,1],"_match":0,oper:0,among:0,own:0,effici:0,onc:0,modul:[0,1],within:0,prefer:0,easy_instal:0,upgrad:0,put:0,unix:0,"boolean":0,divis:0,wrap:0,instal:[0,1],your:0,fanci:0,smith:0,late:0,given:0,from:0,describ:0,simpli:0,support:0,swoop:0,delcar:0,"class":0,avail:0,few:0,much:0,interfac:0,too:0,call:0,underli:0,john:0,valueerror:0,quickli:0,"function":0,funnel:0,sudo:0,option:0,findal:0,globtast:0,under:0,assert:0,part:0,understand:0,togeth:0,els:0,eas:0,exactli:0,effort:0,than:0,matter:0,multi:0,jonathan:0,word:0,sometim:0,possibl:0,provid:0,properti:0,harder:0,see:0,trick:0,defin:0,below:0,can:0,posit:0,exist:0,more:0,thu:0,loop:0,pre:0,passant:[0,1],want:0,look:0,year:0,side:0,doesn:0,compon:0,packag:0,right:0,have:0,tabl:1,pip:0,unsubclass:0,work:0,string:0,huge:0,answer:0,welcom:[0,1],turn:0,suggest:0,make:0,whei:0,excel:0,pytest:0,same:0,note:[0,1],also:0,need:0,other:0,memoiz:0,which:0,test:0,you:0,document:1,simpl:0,simplifi:0,legitim:0,goe:0,regardless:0,though:0,glob:[0,1],time:0,effect:0,preced:0,rematch:0,regular:0,intent:0,boiler:0,mai:0,underscor:0,implement:0,tradit:0,redefin:0,appropri:0,don:0,nativ:0,condit:0,clear:0,author:0,well:0,strategi:0,rais:0,assign:0,person:0,exampl:0,command:0,thi:0,titl:[],findit:0,fallback:0,order:0,latest:0},objtypes:{},titles:["Usage","Welcome to simplere&#8217;s documentation!"],objnames:{},filenames:["README","index"]})
+Search.setIndex({objects:{},terms:{all:1,code:[0,1],lack:[0,1],prefix:1,follow:1,program:1,swoop:1,under:1,sens:1,worth:1,consum:1,string:[0,1],fals:1,fall:1,appar:1,tri:[0,1],level:0,fewer:[0,1],"try":1,item:1,small:1,second:1,pass:[0,1],even:1,index:[],what:1,appear:1,compar:1,section:1,introspect:1,access:[0,1],experiment:1,method:1,elimin:[0,1],full:0,gener:[],here:1,along:0,vertic:1,valu:1,intension:1,search:[0,1],larger:1,amount:1,action:[0,1],implement:1,regardless:1,"_sre":1,modul:1,prefer:1,ask:1,unix:[0,1],"boolean":1,instal:[0,1],establish:1,regex:1,wonderfulli:1,describ:1,memori:1,upgrad:1,few:1,call:1,jonathan:1,tightli:1,more:1,desir:1,effort:1,must:1,fly:1,word:1,valuabl:[0,1],work:1,can:[0,1],sudo:1,indic:1,want:[],unsubclass:1,huge:1,multipl:[0,1],thing:1,anoth:1,divis:1,how:1,memoiz:1,pure:1,answer:1,simpl:[0,1],product:1,alwai:1,befor:1,mai:1,underscor:1,parallel:1,alias:1,preced:1,fallback:1,order:1,over:1,held:1,through:1,still:1,style:[],group:[0,1],"_match":1,better:1,pytest:1,them:1,good:1,"return":1,thei:1,python:[0,1],mention:1,nor:1,slicker:1,name:1,bonu:[0,1],easili:1,found:1,side:1,compil:1,hard:1,realli:1,year:1,beyond:1,out:1,variabl:1,space:1,some_str:[0,1],content:[],print:[0,1],proxi:1,manipul:0,tox:1,standard:1,base:1,put:1,jeunic:1,motion:[0,1],turn:1,assign:[0,1],oper:1,onc:1,number:1,alreadi:[],done:1,fanci:1,given:1,interwoven:1,sometim:1,too:1,john:1,option:1,travi:1,part:1,findit:1,exactli:1,than:1,provid:[0,1],structur:1,matter:1,posit:1,pre:[0,1],passant:[0,1],ani:1,packag:1,have:1,tabl:[],need:1,seem:1,note:1,also:[0,1],take:1,exploratori:1,singl:1,simplifi:[0,1],though:1,glob:[0,1],object:1,rematch:1,regular:[0,1],phase:1,"class":1,tradit:1,don:1,doc:0,clear:1,later:1,cover:1,doe:1,particularli:0,fine:1,eas:[],pretti:1,version:1,plate:1,get:1,express:[0,1],pypi:1,wonderfuli:[],autom:1,nativ:1,requir:[0,1],contain:1,view:1,set:1,see:[0,1],result:[0,1],fail:1,best:1,wonder:1,pattern:[0,1],boundari:1,tend:1,"import":[0,1],attribut:1,numer:1,both:1,equal:1,against:1,logic:1,mani:1,comment:1,among:1,simpli:[],had:1,commenc:1,late:1,delcar:[],been:1,compon:1,much:1,threaten:1,valueerror:[0,1],quickli:[],assert:1,findal:1,togeth:1,"case":1,multi:1,look:1,properti:1,harder:1,trick:1,defin:1,"while":1,abov:1,error:[0,1],loop:1,orent:[],motiv:1,around:1,develop:1,welcom:1,author:1,suggest:1,make:1,format:[0,1],same:1,complex:[0,1],preparatori:[0,1],document:0,optim:1,effect:1,moment:1,rais:[0,1],boiler:1,chang:1,redefin:1,appropri:1,thu:1,well:1,person:1,exampl:1,command:1,thi:1,programm:1,model:1,latest:1,just:1,less:1,when:1,languag:[0,1],sre_match:1,expos:1,smith:1,add:1,other:1,els:[0,1],save:1,eunic:1,match:[0,1],real:1,which:1,mayb:1,read:0,verion:[],python3:1,like:1,specif:1,collect:1,either:1,cascad:1,manag:1,underli:1,right:1,old:1,often:1,twitter:1,compat:[0,1],back:1,guarante:1,successfulli:1,subclass:1,condit:[0,1],complic:1,power:[0,1],usag:[0,1],step:[0,1],from:[0,1],post:[0,1],simpler:[0,1],prove:1,page:[],globtast:[0,1],own:1,effici:1,within:1,easy_instal:1,wrap:1,your:1,wai:[0,1],quirki:1,support:1,fast:1,avail:1,interfac:[0,1],lot:1,"function":1,funnel:[],line:1,"true":1,possibl:1,below:1,strategi:1,doesn:1,exist:[],pip:1,check:[0,1],titl:[],whei:1,excel:1,cleanup:0,test:[0,1],you:[0,1],legitim:1,condens:1,fell:1,intent:1,goe:1,time:1,push:1,understand:1},objtypes:{},titles:["Usage","simplere"],objnames:{},filenames:["README","index"]})

File docs/index.rst

View file
  • Ignore whitespace
 motion and then a test::
 
     import re
-    
+
     match = re.search(pattern, some_string)
     if match:
         print match.group(1)
     if match / re.search(pattern, some_string):
         print match[1]
 
-Or with an object-orented style::
+Motivation
+==========
 
-    if some_string in Re(pattern):
-        print Re._[1]
+In the simple examples above, "fewer steps" seems like a small
+savings (3 lines to 2). While a 33% savings is a pretty good
+optimization, is it really worth using another module and
+a quirky *en passant* operator to get it?
+
+In code this simple, maybe not. But real regex-based searching tends
+to have multiple, cascading searches, and to be tightly interwoven
+with complex pre-conditions, error-checking, and post-match formatting
+or actions. It gets complicated fast. When multiple ``re`` matches
+must be done, it consumes a lot of "vertical space" and often
+threatens to push the number of lines a programmer is viewing at
+any given moment beyond the number that can be easily held in working
+memory. In that case, it proves valuable to condense what is logically
+a single operation ("regular expression test") into a single line
+with its conditional ``if``.
+
+This is even more true for the "exploratory" phases of development,
+before a program's appropriate structure and best logical boundaries
+have been established.  One can always "back out" the condensing *en
+passant* operation in later production code, if desired.
 
 .. toctree::
    :maxdepth: 2
         print Re._.name, "is", Re._.age, "years old"
     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
 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'):
         print found[1]
-        
+
 Or collect them all in one fell swoop::
 
     found = Re('pattern (\w+)').findall('pattern is as pattern does')
-    
+
 Pretty much all of the methods and properties one can access from the standard
 ``re`` module are available.
 
 Bonus: Globs
 ============
 
-Regular expressions are wonderfuly powerful, but sometimes the simpler `Unix glob
+Regular expressions are wonderfully powerful, but sometimes the simpler `Unix glob
 <http://en.wikipedia.org/wiki/Glob_(programming)>`_ is works just fine. As a bonus,
 ``simplere`` also provides simple glob access.::
 
     else:
         raise ValueError('YES IT IS')
 
-En Passant
-==========
+En Passant, Under the Covers
+============================
 
-If you have existing code that already uses ``re`` regular expressions
-and you want to ease into using ``simplere``, ``ReMatch`` objects can
-simply wrap Python's native``_sre.SRE_Match`` objects (the things that ``re``
+``ReMatch`` objects
+wrap Python's native``_sre.SRE_Match`` objects (the things that ``re``
 method calls return).::
 
     match = re.match(r'(?P<word>th.s)', 'this is a string')
         print match.group(1)    # still works
         print match[1]          # same thing
         print match.word        # same thing, with logical name
-        
+
 But that's a huge amount of boiler plate for a simple test, right? So ``simplere``
-also uses an *en passant* trick of redefining the division operation::
-    
+*en passant* operator redefining the division operation and proxies the ``re`` result
+on the fly to the pre-defined ``match`` object::
+
     if match / re.search(r'(?P<word>th.s)', 'this is a string'):
         assert match[1] == 'this'
         assert match.word == 'this'
         assert match.group(1) == 'this'
 
-This uses the pre-delcared ``match`` object and the division operator (``/``)
-to quickly funnel
-the result of the search. 
 If the ``re`` operation fails, the resulting object is guaranteed to have
-a ``False``-like boolean value, so that it will fall through conditional tests. 
+a ``False``-like Boolean value, so that it will fall through conditional tests.
 
 If you prefer the look of the less-than (``<``) or less-than-or-equal (``<=``),
 as indicators that ``match`` takes the value of the following function call, they
-are supported as aliases of the division operation (``/``). You may define your
+are experimentally supported as aliases of the division operation (``/``).
+You may define your
 own match objects, and can use them on memoized ``Re`` objects too. Putting
 a few of these optional things together::
 
     answer = Match()   # need to do this just once
-    
+
     if answer < Re(r'(?P<word>th..)').search('and that goes there'):
         assert answer.word == 'that'
 
 Notes
 =====
-   
+
  *  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).
- 
+    successfully packaged for, and tested against, all late-model versions of
+    Python: 2.6, 2.7, 3.2, and 3.3, as well as PyPy 2.1 (based on 2.7.3).
+    Travis-CI testing has also commenced.
+
  *  ``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.
 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 these with "sudo " to authorize installation.)
-
-

File setup.py

View file
  • Ignore whitespace
 
 setup(
     name='simplere',
-    version='1.0.4',
+    version='1.0.5',
     author='Jonathan Eunice',
     author_email='jonathan.eunice@gmail.com',
     description='Simpler, cleaner access to regular expressions. Globs too.',