
[This is just an excerpt from an email I wrote someone explaining
 roughly how Esrapy goes about parsing.  Note, however, this doesn't
 really clarify how the code is arranged since the functionality
 described below is the composite behavior of the Core module plus
 the various Pattern objects.... But it gives a good picture of what
 it does, if not exactly how.]

    - Esrapy is looking for something at the beginning of the file -- the
file pattern that you've provided it to look for.  Call this pattern P.

    - If P is a raw string or regular expression, then it just looks to
see if it's there (just in the exact place it is looking for it).

    - Otherwise, Esrapy knows P is made up of other patterns, so:

    - If P is made up of a series of other patterns, then Esrapy
starts looking for the first thing in the series (and thus the process
starts over recursively at step 2 above).  If it finds it, then
it moves on to looking for the next item in the series--at the position
where the previous one ended--and so on.

    - If P is made up of a set of options, then Esrapy starts looking
for the first one first (recursing as above) and if it fails to
find it, then it looks for the second one, and so on.

    And that's basically it!  The above, of course, essentially
describes a simple recursive-descent parser.

    There are two subtleties, however.  The first of these is a concept
implicitly employed by chart parsers, and the second by packrat parsers:

    - If Esrapy finds itself looking for something it's already looking
for (such as when a pattern is recursively composed of itself), it
doesn't start looking *again* since it's already looking, it just
remembers the context in which it was looking (and notifies that context
if the pattern in question is later found).

    - If Esrapy finds itself looking for something it's already *found*,
it remembers that it found it before and just uses its memory rather
than looking for it all over again.

    And that's pretty much the whole of it.

