Scans the source for a given pattern. Note, that this is not your usual
scan() method. For one thing, the pattern argument has some requirements;
for another, the source can be consumed. You can easily confuse this
method. Originally, the patterns were easier to construct and this method
more robust, because this method generated search regexes on the fly;
however, this was computationally expensive and slowed down the entire
REXML package considerably, since this is by far
the most commonly called method. @param pattern must be a Regexp, and must
be in the form of /^\s*(#{your pattern, with no groups})(.*)/. The first
group will be returned; the second group is used if the consume flag is
set. @param consume if true, the pattern returned will be consumed, leaving
everything after it in the
Source. @return the
pattern, if found, or nil if the
Source is empty
or the pattern is not found.
