<!DOCTYPE class>
<class name='Source'>
   A Source can be searched for patterns, and wraps buffers and other objects and provides consumption of text
  <attribute name='buffer' type='reader'>
     The current buffer (what we're going to read next)
  </attribute>
  <attribute name='line' type='reader'>
     The line number of the last consumed text
  </attribute>
  <method name='initialize'>
    <argument name='arg'>
      must be a String, and should be a valid XML document
    </argument>
     Constructor 
  </method>
  <method name='scan'>
    <argument name='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. 
    </argument>
    <argument default='false' name='consume'>
      if true, the pattern returned will be consumed, leaving everything after it in the Source. 
    </argument>
    <return>
      the pattern, if found, or nil if the Source is empty or the pattern is not found.
    </return>
     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. 
  </method>
  <method name='match'>
    <argument name='pattern'/>
    <argument default='false' name='consume'/>
  </method>
  <method name='empty'>
    <return>
      true if the Source is exhausted
    </return>
     
  </method>
</class>