citrus 1.8.0 → 2.0.0

data/benchmark/master.dat

@@ -0,0 +1,192 @@
+12 0
+30 0
+35 0
+1749 19
+1962 49
+2383 10
+3728 49
+3919 59
+3952 60
+3995 49
+4063 50
+4325 70
+4527 60
+4570 60
+4607 70
+4654 59
+4679 70
+4774 59
+4968 70
+5059 39
+5383 39
+5915 70
+6109 70
+6122 80
+6218 90
+6332 70
+6681 59
+7440 90
+7530 80
+7605 79
+8155 89
+8402 100
+8420 100
+8617 110
+8635 109
+8841 120
+8843 109
+8852 100
+9151 99
+9271 89
+9521 99
+9525 89
+9566 100
+9584 109
+9642 110
+10138 130
+10181 109
+10225 109
+10338 110
+10449 99
+10629 100
+10763 129
+10817 130
+11059 120
+11062 120
+11215 119
+11698 129
+11891 120
+11945 139
+11956 129
+12018 150
+12053 109
+12178 140
+12283 119
+12326 99
+12430 119
+12438 130
+12572 130
+12638 129
+12687 130
+12703 129
+12896 129
+12922 120
+12996 129
+13137 170
+13211 140
+13462 140
+13477 129
+13576 140
+13577 140
+13584 129
+13605 130
+13631 160
+14216 150
+14237 139
+14260 130
+14367 129
+14371 160
+14741 170
+14893 139
+14910 160
+14917 149
+14977 149
+15049 150
+15191 179
+15382 150
+15618 179
+15623 179
+15629 150
+15856 170
+16496 200
+16512 160
+16956 179
+17074 149
+17237 189
+17371 170
+17568 189
+17945 199
+18147 190
+18343 210
+18417 199
+18823 200
+18970 210
+19285 220
+19333 189
+19500 199
+19548 219
+19634 189
+19673 209
+19689 209
+19909 199
+20054 199
+20107 229
+20248 219
+20580 219
+20744 230
+20806 210
+20954 230
+21034 209
+21187 199
+21303 239
+21450 209
+21626 189
+21931 289
+21950 230
+22359 250
+22626 209
+22638 279
+22772 250
+22885 259
+22897 240
+23114 330
+23242 229
+23428 279
+23452 240
+23495 250
+23499 260
+23558 270
+23744 220
+23881 240
+23945 269
+24361 250
+24501 240
+24642 269
+24672 249
+24694 219
+24706 270
+24931 290
+25065 300
+25140 290
+25402 250
+25702 289
+25743 290
+27139 359
+27316 299
+27333 290
+27414 309
+27771 309
+27798 259
+28583 320
+28906 309
+29025 360
+29209 310
+29272 280
+29273 310
+29359 270
+29577 330
+30886 359
+31170 359
+31593 330
+32460 369
+32486 390
+32630 399
+33010 440
+33137 419
+33142 389
+33739 340
+39880 470
+39940 460
+42952 489
+43227 500
+52855 640

data/doc/background.markdown

@@ -29,9 +29,9 @@ A [Rule](api/classes/Citrus/Rule.html) is an object that specifies some matching
 behavior on a string. There are two types of rules: terminals and non-terminals.
 Terminals can be either Ruby strings or regular expressions that specify some
 input to match. For example, a terminal created from the string "end" would
-match any sequence of the characters "e", "n", and "d", in that order. A
-terminal created from a regular expression uses Ruby's regular expression engine
-to attempt to create a match.
+match any sequence of the characters "e", "n", and "d", in that order. Terminals
+created from regular expressions may match any sequence of characters that can
+be generated from that expression.
 
 Non-terminals are rules that may contain other rules but do not themselves match
 directly on the input. For example, a Repeat is a non-terminal that may contain
@@ -58,10 +58,10 @@ similar to Ruby's super keyword.
 ## Matches
 
 Matches are created by rule objects when they match on the input. A 
-[Match](api/classes/Citrus/Match.html) in Citrus is actually a 
-[String](http://ruby-doc.org/core/classes/String.html) with some extra 
-information attached such as the name(s) of the rule(s) which generated the 
-match as well as its offset in the original input string.
+[Match](api/classes/Citrus/Match.html) is actually a 
+[String](http://ruby-doc.org/core/classes/String.html) object with some extra 
+information attached such as the name(s) of the rule(s) from which it was
+generated and any submatches it may contain.
 
 During a parse, matches are arranged in a tree structure where any match may
 contain any number of other matches. This structure is determined by the way in
@@ -70,6 +70,5 @@ match that is created from a non-terminal rule that contains several other
 terminals will likewise contain several matches, one for each terminal.
 
 Match objects may be extended with semantic information in the form of methods.
-These methods can interpret the text of a match using the wealth of information
-available to them including the text of the match, its position in the input,
-and any submatches.
+These methods should provide various interpretations for the semantic value of a
+match.

data/doc/example.markdown

@@ -47,9 +47,9 @@ Submatches are created whenever a rule contains another rule. For example, in
 the grammar above the number rule matches a string of digits followed by white
 space. Thus, a match generated by the number rule will contain two submatches.
 
-We can use Ruby's block syntax to create a module that will be attached to these
-matches when they are created and is used to lazily extend them when we want to
-interpret them. The following example shows one way to do this.
+We can define methods inside a set of curly braces that will be used to extend
+matches when they are created. This works in similar fashion to using Ruby's
+blocks. Let's extend the `Addition` grammar using this technique.
 
     grammar Addition
       rule additive
@@ -83,25 +83,27 @@ on all match objects that result from matches of those particular rules. It's
 easiest to explain what is going on here by starting with the lowest level
 block, which is defined within the number rule.
 
-The semantic block associated with the number rule defines one method, value.
+The semantic block associated with the number rule defines one method, `value`.
 Inside this method, we can see that the value of a number match is determined to
-be its text value, stripped of white space and converted to an integer. Remember
-that matches are simply strings, so the `strip` method in this case is actually
-`String#strip`.
-
-The `additive` rule also extends its matches with a value method. Notice the use
-of the `term` label within the rule definition. This label allows the match that
-is created by either the additive or the number rule to be retrieved using the
-`term` label. The value of an additive is determined to be the values of its
+be its text value, stripped of white space and converted to an integer.
+[Remember](background.html) that matches are simply strings, so the `strip`
+method in this case is actually
+[String#strip](http://ruby-doc.org/core/classes/String.html#M000820).
+
+The `additive` rule also extends its matches with a `value` method. Notice the
+use of the `term` label within the rule definition. This label allows the match
+that is created by either the additive or the number rule to be retrieved using
+the `term` label. The value of an additive is determined to be the values of its
 `number` and `term` matches added together using Ruby's addition operator.
 
 Since additive is the first rule defined in the grammar, any match that results
 from parsing a string with this grammar will have a `value` method that can be
 used to recursively calculate the collective value of the entire match tree.
 
-To give it a try, save the code for the Addition grammar in a file called
-addition.citrus. Next, assuming you have the Citrus gem installed, try the
-following sequence of commands in a terminal.
+To give it a try, save the code for the `Addition` grammar in a file called
+addition.citrus. Next, assuming you have the Citrus
+[gem](https://rubygems.org/gems/citrus) installed, try the following sequence of
+commands in a terminal.
 
     $ irb
     > require 'citrus'
@@ -115,6 +117,13 @@ following sequence of commands in a terminal.
 
 Congratulations! You just ran your first piece of Citrus code.
 
+One interesting thing to notice about the above sequence of commands is the
+return value of [Citrus#load](api/classes/Citrus.html#M000003). When you use
+`Citrus.load` to
+load a grammar file (and likewise [Citrus#eval](api/classes/Citrus.html#M000004) to evaluate
+a raw string of grammar code), the return value is an array of all the grammars
+present in that file.
+
 Take a look at 
 [examples/calc.citrus](http://github.com/mjijackson/citrus/blob/master/examples/calc.citrus)
 for an example of a calculator that is able to parse and evaluate more complex 

data/doc/syntax.markdown

@@ -21,8 +21,7 @@ compatibility with other parsing expression implementations.
     [\x00-\xFF]   # match any octet
     .             # match anything, even new lines
 
-See [FixedWidth](api/classes/Citrus/FixedWidth.html) and
-[Expression](api/classes/Citrus/Expression.html) for more information.
+See [Terminal](api/classes/Citrus/Terminal.html) for more information.
 
 ## Repetition
 
@@ -108,22 +107,22 @@ See [Label](api/classes/Citrus/Label.html) for more information.
 The following table contains a list of all Citrus operators and their 
 precedence. A higher precedence indicates tighter binding.
 
-| Operator     | Name                      | Precedence
-| ------------ | ------------------------- | ----------
-| ''           | String (single quoted)    | 6
-| ""           | String (double quoted)    | 6
-| []           | Character class           | 6
-| .            | Dot (any character)       | 6
-| //           | Regular expression        | 6
-| ()           | Grouping                  | 6
-| *            | Repetition (arbitrary)    | 5
-| +            | Repetition (one or more)  | 5
-| ?            | Repetition (zero or one)  | 5
-| &            | And predicate             | 4
-| !            | Not predicate             | 4
-| ~            | But predicate             | 4
-| :            | Label                     | 4
-| <>           | Extension (module name)   | 3
-| {}           | Extension (literal)       | 3
-| e1 e2        | Sequence                  | 2
-| e1 &#124; e2 | Ordered choice            | 1
+Operator                  | Name                      | Precedence
+------------------------- | ------------------------- | ----------
+`''`                      | String (single quoted)    | 6
+`""`                      | String (double quoted)    | 6
+`[]`                      | Character class           | 6
+`.`                       | Dot (any character)       | 6
+`//`                      | Regular expression        | 6
+`()`                      | Grouping                  | 6
+`*`                       | Repetition (arbitrary)    | 5
+`+`                       | Repetition (one or more)  | 5
+`?`                       | Repetition (zero or one)  | 5
+`&`                       | And predicate             | 4
+`!`                       | Not predicate             | 4
+`~`                       | But predicate             | 4
+`:`                       | Label                     | 4
+`<>`                      | Extension (module name)   | 3
+`{}`                      | Extension (literal)       | 3
+`e1 e2`                   | Sequence                  | 2
+<code>e1 &#124; e2</code> | Ordered choice            | 1

data/lib/citrus.rb

@@ -1,3 +1,5 @@
+require 'strscan'
+
 # Citrus is a compact and powerful parsing library for Ruby that combines the
 # elegance and expressiveness of the language with the simplicity and power of
 # parsing expressions.
@@ -6,14 +8,14 @@
 module Citrus
   autoload :File, 'citrus/file'
 
-  VERSION = [1, 8, 0]
+  VERSION = [2, 0, 0]
 
   # Returns the current version of Citrus as a string.
   def self.version
     VERSION.join('.')
   end
 
-  # A pattern to match any character, including \n.
+  # A pattern to match any character, including \\n.
   DOT = /./m
 
   Infinity = 1.0 / 0
@@ -39,25 +41,77 @@ module Citrus
   class ParseError < Exception
     def initialize(input)
       @input = input
-      c = consumed
-      s = [0, c.length - 40].max
-      msg  = "Failed to parse input at offset %d" % max_offset
-      msg += ", just after %s" % c[s, c.length].inspect + "\n"
+      msg = "Failed to parse input at offset %d" % offset
+      msg << detail
       super(msg)
     end
 
     # The Input object that was used for the parse.
     attr_reader :input
 
-    # Returns the maximum offset that was reached before the error occurred.
-    def max_offset
+    # Returns the 0-based offset at which the error occurred in the input, i.e.
+    # the maximum offset in the input that was successfully parsed before the
+    # error occurred.
+    def offset
       input.max_offset
     end
 
-    # Returns the portion of the input string that was successfully consumed
-    # before the parse failed.
-    def consumed
-      input[0, max_offset]
+    # Returns the text of the line on which the error occurred.
+    def line
+      lines[line_index]
+    end
+
+    # Returns the 1-based number of the line in the input where the error
+    # occurred.
+    def line_number
+      line_index + 1
+    end
+
+    alias lineno line_number
+
+    # Returns the 0-based offset at which the error occurred on the line on
+    # which it occurred.
+    def line_offset
+      pos = 0
+      each_line do |line|
+        len = line.length
+        return (offset - pos) if pos + len >= offset
+        pos += len
+      end
+      0
+    end
+
+    # Returns a string that, when printed, gives a visual representation of
+    # exactly where the error occurred on its line in the input.
+    def detail
+      "%s\n%s^" % [line, ' ' * line_offset]
+    end
+
+  private
+
+    def string
+      input.string
+    end
+
+    def lines
+      string.send(string.respond_to?(:lines) ? :lines : :to_s).to_a
+    end
+
+    def each_line(&block)
+      string.each_line(&block)
+    end
+
+    # Returns the 0-based number of the line in the input where the error
+    # occurred.
+    def line_index
+      pos = 0
+      idx = 0
+      each_line do |line|
+        pos += line.length
+        return idx if pos >= offset
+        idx += 1
+      end
+      0
     end
   end
 
@@ -84,6 +138,7 @@ module Citrus
     # exposes Module#include.
     def self.included(mod)
       mod.extend(GrammarMethods)
+      # Expose #include so it can be called publicly.
       class << mod; public :include end
     end
   end
@@ -91,7 +146,7 @@ module Citrus
   # Contains methods that are available to Grammar modules at the class level.
   module GrammarMethods
     def self.extend_object(obj)
-      raise ArgumentError, "Grammars must be Ruby modules" unless Module === obj
+      raise ArgumentError, "Grammars must be Modules" unless Module === obj
       super
     end
 
@@ -153,9 +208,9 @@ module Citrus
     # It is important to note that this method will also check any included
     # grammars for a rule with the given +name+ if one cannot be found in this
     # grammar.
-    def rule(name, obj=nil)
+    def rule(name, obj=nil, &block)
       sym = name.to_sym
-      obj = Proc.new.call if block_given?
+      obj = block.call if block
 
       if obj
         rule_names << sym unless has_rule?(sym)
@@ -256,9 +311,9 @@ module Citrus
     # Specifies a Module that will be used to extend all matches created with
     # the given +rule+. A block may also be given that will be used to create
     # an anonymous module. See Rule#ext=.
-    def ext(rule, mod=nil)
+    def ext(rule, mod=nil, &block)
       rule = Rule.new(rule)
-      mod = Proc.new if block_given?
+      mod = block if block
       rule.extension = mod if mod
       rule
     end
@@ -273,9 +328,11 @@ module Citrus
       root_rule = rule(opts[:root])
       raise 'No rule named "%s"' % root unless root_rule
 
-      input = Input.new(string, opts[:memoize])
-      match = input.match(root_rule, opts[:offset])
+      input = Input.new(string)
+      input.memoize! if opts[:memoize]
+      input.pos = opts[:offset] if opts[:offset] > 0
 
+      match = input.match(root_rule)
       if match.nil? || (opts[:consume] && input.length != match.length)
         raise ParseError.new(input)
       end
@@ -290,10 +347,8 @@ module Citrus
     # root::      The name of the root rule to use for the parse. Defaults
     #             to the name supplied by calling #root.
     # memoize::   If this is +true+ the matches generated during a parse are
-    #             memoized. This technique (also known as Packrat parsing)
-    #             guarantees parsers will operate in linear time but costs
-    #             significantly more in terms of time and memory required.
-    #             Defaults to +false+.
+    #             memoized. See Input#memoize! for more information. Defaults to
+    #             +false+.
     # consume::   If this is +true+ a ParseError will be raised during a parse
     #             unless the entire input string is consumed. Defaults to
     #             +false+.
@@ -308,61 +363,80 @@ module Citrus
 
   # This class represents the core of the parsing algorithm. It wraps the input
   # string and serves matches to all nonterminals.
-  class Input
-    # Takes the input +string+ that is to be parsed. If +memoize+ is +true+
-    # a cache is created that holds references to already generated matches.
-    def initialize(string, memoize=false)
-      @string = string
+  class Input < StringScanner
+    def initialize(string)
+      super(string)
       @max_offset = 0
-      if memoize
-        @cache = {}
-        @cache_hits = 0
-      end
     end
 
-    # The input string.
-    attr_reader :string
-
-    # The maximum offset that has been achieved.
+    # The maximum offset that has been achieved during a parse.
     attr_reader :max_offset
 
-    # A two-level hash of rule id's and offsets to their respective matches.
-    # Only present if memoing is enabled.
+    # A nested hash of rule id's to offsets and their respective matches. Only
+    # present if memoing is enabled.
     attr_reader :cache
 
     # The number of times the cache was hit. Only present if memoing is enabled.
     attr_reader :cache_hits
 
-    # Sends all arguments to this input's +string+.
-    def [](*args)
-      @string.__send__(:[], *args)
-    end
-
     # Returns the length of this input.
     def length
-      @string.length
+      string.length
     end
 
-    # Returns the match for a given +rule+ at +offset+. If memoing is enabled
-    # and a match does not already exist for the given rule/offset pair then
-    # the rule is executed and the result is cached before returning. See
-    # http://pdos.csail.mit.edu/~baford/packrat/icfp02/ for more information
-    # on memoing match results (also known as packrat parsing).
-    def match(rule, offset=0)
-      @max_offset = offset if offset > @max_offset
+    # Returns the match for a given +rule+ at the current position in the input.
+    def match(rule)
+      offset = pos
+      match = rule.match(self)
+
+      if match
+        @max_offset = pos if pos > @max_offset
+      else
+        # Reset the position for the next attempt at a match.
+        self.pos = offset
+      end
+
+      match
+    end
 
-      if @cache
-        c = @cache[rule.id] ||= {}
+    # Returns true if this input uses memoization to cache match results. See
+    # #memoize!.
+    def memoized?
+      !! @cache
+    end
+
+    # Modifies this object to cache match results during a parse. This technique
+    # (also known as "Packrat" parsing) guarantees parsers will operate in
+    # linear time but costs significantly more in terms of time and memory
+    # required to perform a parse. For more information, please read the paper
+    # on Packrat parsing at http://pdos.csail.mit.edu/~baford/packrat/icfp02/.
+    def memoize!
+      return if memoized?
+
+      # Using +instance_eval+ here preserves access to +super+ within the
+      # methods we define inside the block.
+      instance_eval do
+        def match(rule)
+          c = @cache[rule.id] ||= {}
+
+          if c.key?(pos)
+            @cache_hits += 1
+            c[pos]
+          else
+            c[pos] = super
+          end
+        end
 
-        if c.key?(offset)
-          @cache_hits += 1
-          c[offset]
-        else
-          c[offset] = rule.match(self, offset)
+        def reset
+          super
+          @max_offset = 0
+          @cache = {}
+          @cache_hits = 0
         end
-      else
-        rule.match(self, offset)
       end
+
+      @cache = {}
+      @cache_hits = 0
     end
   end
 
@@ -380,15 +454,14 @@ module Citrus
     # Returns a new Rule object depending on the type of object given.
     def self.new(obj)
       case obj
-      when Rule     then obj
-      when Symbol   then Alias.new(obj)
-      when String   then FixedWidth.new(obj)
-      when Regexp   then Expression.new(obj)
-      when Array    then Sequence.new(obj)
-      when Range    then Choice.new(obj.to_a)
-      when Numeric  then FixedWidth.new(obj.to_s)
+      when Rule           then obj
+      when Symbol         then Alias.new(obj)
+      when String, Regexp then Terminal.new(obj)
+      when Array          then Sequence.new(obj)
+      when Range          then Choice.new(obj.to_a)
+      when Numeric        then Terminal.new(obj.to_s)
       else
-        raise ArgumentError, "Invalid rule object: #{obj.inspect}"
+        raise ArgumentError, "Invalid rule object: %s" % obj.inspect
       end
     end
 
@@ -466,9 +539,8 @@ module Citrus
       match
     end
 
-    def create_match(data, offset)
-      match = Match.new(data, offset)
-      extend_match(match, name)
+    def create_match(data)
+      extend_match(Match.new(data), name)
     end
   end
 
@@ -496,10 +568,9 @@ module Citrus
       @rule ||= resolve!
     end
 
-    # Returns the Match for this proxy's #rule on +input+ at the given +offset+,
-    # +nil+ if no match can be made.
-    def match(input, offset=0)
-      m = input.match(rule, offset)
+    # Returns the Match for this rule on +input+, +nil+ if no match can be made.
+    def match(input)
+      m = input.match(rule)
       extend_match(m, name) if m
     end
   end
@@ -558,49 +629,15 @@ module Citrus
   end
 
   # A Terminal is a Rule that matches directly on the input stream and may not
-  # contain any other rule.
-  module Terminal
-    include Rule
-
-    def initialize(rule)
-      @rule = rule
-    end
-
-    # The actual String or Regexp object this rule uses to match.
-    attr_reader :rule
-
-    # Returns the Citrus notation of this rule as a string.
-    def to_s
-      rule.inspect
-    end
-  end
-
-  # A FixedWidth is a Terminal that matches based on its length. The Citrus
-  # notation is any sequence of characters enclosed in either single or double
-  # quotes, e.g.:
+  # contain any other rule. Terminals may be created from either a String or a
+  # Regexp object. When created from strings, the Citrus notation is any
+  # sequence of characters enclosed in either single or double quotes, e.g.:
   #
   #     'expr'
   #     "expr"
   #
-  class FixedWidth
-    include Terminal
-
-    def initialize(rule='')
-      raise ArgumentError, "FixedWidth must be a String" unless String === rule
-      super
-    end
-
-    # Returns the Match for this rule on +input+ at the given +offset+, +nil+ if
-    # no match can be made.
-    def match(input, offset=0)
-      create_match(rule.dup, offset) if input[offset, rule.length] == rule
-    end
-  end
-
-  # An Expression is a Terminal that has the same semantics as a regular
-  # expression in Ruby. The expression must match at the beginning of the input
-  # (index 0). The Citrus notation is identical to Ruby's regular expression
-  # notation, e.g.:
+  # When created from a regular expression, the Citrus notation is identical to
+  # Ruby's regular expression notation, e.g.:
   #
   #     /expr/
   #
@@ -610,19 +647,34 @@ module Citrus
   #     [a-zA-Z]
   #     .
   #
-  class Expression
-    include Terminal
+  class Terminal
+    include Rule
 
-    def initialize(rule=/^/)
-      raise ArgumentError, "Expression must be a Regexp" unless Regexp === rule
-      super
+    def initialize(rule='')
+      case rule
+      when String
+        @string = rule
+        @rule = Regexp.new(Regexp.escape(rule))
+      when Regexp
+        @rule = rule
+      else
+        raise ArgumentError, "Cannot create terminal from object: %s" % 
+          rule.inspect
+      end
     end
 
-    # Returns the Match for this rule on +input+ at the given +offset+, +nil+ if
-    # no match can be made.
-    def match(input, offset=0)
-      m = input[offset, input.length - offset].match(rule)
-      create_match(m, offset) if m && m.begin(0) == 0
+    # The actual Regexp object this rule uses to match.
+    attr_reader :rule
+
+    # Returns the Match for this rule on +input+, +nil+ if no match can be made.
+    def match(input)
+      m = input.scan(@rule)
+      create_match(m) if m
+    end
+
+    # Returns the Citrus notation of this rule as a string.
+    def to_s
+      (@string || @rule).inspect
     end
   end
 
@@ -669,10 +721,9 @@ module Citrus
   class AndPredicate
     include Predicate
 
-    # Returns the Match for this rule on +input+ at the given +offset+, +nil+ if
-    # no match can be made.
-    def match(input, offset=0)
-      create_match('', offset) if input.match(rule, offset)
+    # Returns the Match for this rule on +input+, +nil+ if no match can be made.
+    def match(input)
+      create_match('') if input.match(rule)
     end
 
     # Returns the Citrus notation of this rule as a string.
@@ -690,10 +741,9 @@ module Citrus
   class NotPredicate
     include Predicate
 
-    # Returns the Match for this rule on +input+ at the given +offset+, +nil+ if
-    # no match can be made.
-    def match(input, offset=0)
-      create_match('', offset) unless input.match(rule, offset)
+    # Returns the Match for this rule on +input+, +nil+ if no match can be made.
+    def match(input)
+      create_match('') unless input.match(rule)
     end
 
     # Returns the Citrus notation of this rule as a string.
@@ -713,19 +763,16 @@ module Citrus
 
     DOT_RULE = Rule.new(DOT)
 
-    # Returns the Match for this rule on +input+ at the given +offset+, +nil+ if
-    # no match can be made.
-    def match(input, offset=0)
+    # Returns the Match for this rule on +input+, +nil+ if no match can be made.
+    def match(input)
       matches = []
-      os = offset
-      while input.match(rule, os).nil?
-        m = input.match(DOT_RULE, os)
+      while input.match(rule).nil?
+        m = input.match(DOT_RULE)
         break unless m
         matches << m
-        os += m.length
       end
       # Create a single match from the aggregate text value of all submatches.
-      create_match(matches.join, offset) if matches.any?
+      create_match(matches.join) if matches.any?
     end
 
     # Returns the Citrus notation of this rule as a string.
@@ -757,11 +804,11 @@ module Citrus
     # The label this rule adds to all its matches.
     attr_reader :label
 
-    # Returns the Match for this rule on +input+ at the given +offset+, +nil+ if
-    # no match can be made. When a Label makes a match, it re-names the match to
-    # the value of its label.
-    def match(input, offset=0)
-      m = input.match(rule, offset)
+    # Returns the Match for this rule on +input+, +nil+ if no match can be made.
+    # When a Label makes a match, it re-names the match to the value of its
+    # #label.
+    def match(input)
+      m = input.match(rule)
       extend_match(m, label) if m
     end
 
@@ -799,18 +846,15 @@ module Citrus
       @range = Range.new(min, max)
     end
 
-    # Returns the Match for this rule on +input+ at the given +offset+, +nil+ if
-    # no match can be made.
-    def match(input, offset=0)
+    # Returns the Match for this rule on +input+, +nil+ if no match can be made.
+    def match(input)
       matches = []
-      os = offset
       while matches.length < @range.end
-        m = input.match(rule, os)
+        m = input.match(rule)
         break unless m
         matches << m
-        os += m.length
       end
-      create_match(matches, offset) if @range.include?(matches.length)
+      create_match(matches) if @range.include?(matches.length)
     end
 
     # The minimum number of times this rule must match.
@@ -846,6 +890,7 @@ module Citrus
   module List
     include Nonterminal
 
+    # See Rule#paren?.
     def paren?
       rules.length > 1
     end
@@ -859,11 +904,10 @@ module Citrus
   class Choice
     include List
 
-    # Returns the Match for this rule on +input+ at the given +offset+, +nil+ if
-    # no match can be made.
-    def match(input, offset=0)
+    # Returns the Match for this rule on +input+, +nil+ if no match can be made.
+    def match(input)
       rules.each do |rule|
-        m = input.match(rule, offset)
+        m = input.match(rule)
         return extend_match(m, name) if m
       end
       nil
@@ -883,18 +927,15 @@ module Citrus
   class Sequence
     include List
 
-    # Returns the Match for this rule on +input+ at the given +offset+, +nil+ if
-    # no match can be made.
-    def match(input, offset=0)
+    # Returns the Match for this rule on +input+, +nil+ if no match can be made.
+    def match(input)
       matches = []
-      os = offset
       rules.each do |rule|
-        m = input.match(rule, os)
+        m = input.match(rule)
         break unless m
         matches << m
-        os += m.length
       end
-      create_match(matches, offset) if matches.length == rules.length
+      create_match(matches) if matches.length == rules.length
     end
 
     # Returns the Citrus notation of this rule as a string.
@@ -907,24 +948,19 @@ module Citrus
   # match may contain any number of other matches. This class provides several
   # convenient tree traversal methods that help when examining parse results.
   class Match < String
-    def initialize(data, offset=0)
+    def initialize(data)
       case data
       when String
         super(data)
-      when MatchData
-        super(data[0])
-        @captures = data.captures
       when Array
         super(data.join)
         @matches = data
+      else
+        raise ArgumentError, "Cannot create match from object: %s" % 
+          data.inspect
       end
-
-      @offset = offset
     end
 
-    # The offset in the input at which this match occurred.
-    attr_reader :offset
-
     # An array of all names of this match. A name is added to a match object
     # for each rule that returns that object when matching. These names can then
     # be used to determine which rules were satisfied by a given match.
@@ -947,12 +983,6 @@ module Citrus
       @matches ||= []
     end
 
-    # An array of substrings returned by MatchData#captures if this match was
-    # created by an Expression.
-    def captures
-      @captures ||= []
-    end
-
     # Returns an array of all sub-matches with the given +name+. If +deep+ is
     # +false+, returns only sub-matches that are immediate descendants of this
     # match.