citrus 2.3.1 → 2.3.2

data/lib/citrus.rb

@@ -8,23 +8,19 @@ require 'strscan'
 module Citrus
   autoload :File, 'citrus/file'
 
-  VERSION = [2, 3, 1]
+  # The current version of Citrus as [major, minor, patch].
+  VERSION = [2, 3, 2]
 
-  # 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 newline.
   DOT = /./m
 
   Infinity = 1.0 / 0
 
   CLOSE = -1
 
-  # Parses the given Citrus +code+ using +options+.
-  def self.parse(code, options={})
-    File.parse(code, options)
+  # Returns the current version of Citrus as a string.
+  def self.version
+    VERSION.join('.')
   end
 
   # Evaluates the given Citrus parsing expression grammar +code+ in the global
@@ -37,25 +33,31 @@ module Citrus
   #       end
   #     end
   #     CITRUS
+  #     # => [MyGrammar]
   #
-  def self.eval(code)
-    parse(code).value
+  def self.eval(code, options={})
+    File.parse(code, options).value
   end
 
   # Evaluates the given expression and creates a new Rule object from it.
   #
   #     Citrus.rule('"a" | "b"')
+  #     # => #<Citrus::Rule: ... >
   #
-  def self.rule(expr)
-    parse(expr, :root => :rule_body).value
+  def self.rule(expr, options={})
+    File.parse(expr, options.merge(:root => :rule_body)).value
   end
 
   # Loads the grammar from the given +file+ into the global scope using #eval.
-  def self.load(file)
+  #
+  #     Citrus.load('mygrammar')
+  #     # => [MyGrammar]
+  #
+  def self.load(file, options={})
     file << '.citrus' unless ::File.file?(file)
-    raise "Cannot find file #{file}" unless ::File.file?(file)
-    raise "Cannot read file #{file}" unless ::File.readable?(file)
-    eval(::File.read(file))
+    raise ArgumentError, "Cannot find file #{file}" unless ::File.file?(file)
+    raise ArgumentError, "Cannot read file #{file}" unless ::File.readable?(file)
+    eval(::File.read(file), options)
   end
 
   # A standard error class that all Citrus errors extend.
@@ -157,14 +159,19 @@ module Citrus
       lines[line_index(pos)]
     end
 
+    # Returns +true+ when using memoization to cache match results.
+    def memoized?
+      false
+    end
+
     # Returns an array of events for the given +rule+ at the current pointer
     # position. Objects in this array may be one of three types: a Rule,
     # Citrus::CLOSE, or a length (integer).
     def exec(rule, events=[])
-      index = events.size
       position = pos
+      index = events.size
 
-      if rule.exec(self, events).size > index
+      if apply_rule(rule, position, events).size > index
         position += events[-1]
         @max_offset = position if position > @max_offset
       end
@@ -177,25 +184,27 @@ module Citrus
     # Returns the length of a match for the given +rule+ at the current pointer
     # position, +nil+ if none can be made.
     def test(rule)
-      start = pos
-      events = rule.exec(self)
-      self.pos = start
+      position = pos
+      events = apply_rule(rule, position, [])
+      self.pos = position
       events[-1]
     end
 
-    # Returns +true+ when using memoization to cache match results.
-    def memoized?
-      false
+  private
+
+    # Appends all events for +rule+ at the given +position+ to +events+.
+    def apply_rule(rule, position, events)
+      rule.exec(self, events)
     end
   end
 
-  # A MemoizingInput is an Input that caches segments of the event stream for
+  # A MemoizedInput is an Input that caches segments of the event stream for
   # particular rules in 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/.
-  class MemoizingInput < Input
+  class MemoizedInput < Input
     def initialize(string)
       super(string)
       @cache = {}
@@ -214,31 +223,30 @@ module Citrus
       super
     end
 
-    def exec(rule, events=[]) # :nodoc:
-      position = pos
+    # Returns +true+ when using memoization to cache match results.
+    def memoized?
+      true
+    end
+
+  private
+
+    def apply_rule(rule, position, events) # :nodoc:
       memo = @cache[rule] ||= {}
 
       if memo[position]
         @cache_hits += 1
+        events.concat(memo[position])
       else
-        memo[position] = rule.exec(self)
-      end
+        index = events.size
+        rule.exec(self, events)
 
-      if memo[position].size > 0
-        events.concat(memo[position])
-        position += events[-1]
-        @max_offset = position if position > @max_offset
+        # Memoize the result so we can use it next time this same rule is
+        # executed at this position.
+        memo[position] = events.slice(index, events.size)
       end
 
-      self.pos = position
-
       events
     end
-
-    # Returns +true+ when using memoization to cache match results.
-    def memoized?
-      true
-    end
   end
 
   # Inclusion of this module into another extends the receiver with the grammar
@@ -281,8 +289,9 @@ module Citrus
     # option. Otherwise, all options are the same as in Rule#parse.
     def parse(string, options={})
       rule_name = options.delete(:root) || root
+      raise Error, "No root rule specified" unless rule_name
       rule = rule(rule_name)
-      raise 'No rule named "%s"' % rule_name unless rule
+      raise Error, "No rule named \"#{rule_name}\"" unless rule
       rule.parse(string, options)
     end
 
@@ -511,7 +520,7 @@ module Citrus
         mod = Module.new { define_method(:value, &mod) }
       end
 
-      raise ArgumentError unless Module === mod
+      raise ArgumentError, "Extension must be a Module" unless Module === mod
 
       @extension = mod
     end
@@ -519,22 +528,29 @@ module Citrus
     # The module this rule uses to extend new matches.
     attr_reader :extension
 
+    # The default set of options to use when calling #parse or #test.
+    def default_options # :nodoc:
+      { :consume  => true,
+        :memoize  => false,
+        :offset   => 0
+      }
+    end
+
     # Attempts to parse the given +string+ and return a Match if any can be
-    # made. The +options+ may contain any of the following keys:
+    # made. +options+ may contain any of the following keys:
     #
-    # offset::    The offset in +string+ at which to start the parse. Defaults
-    #             to 0.
+    # consume::   If this is +true+ a ParseError will be raised unless the
+    #             entire input string is consumed. Defaults to +true+.
     # memoize::   If this is +true+ the matches generated during a parse are
-    #             memoized. See Input#memoize! for more information. Defaults to
+    #             memoized. See MemoizedInput 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
-    #             +true+.
+    # offset::    The offset in +string+ at which to start parsing. Defaults
+    #             to 0.
     def parse(string, options={})
-      opts = default_parse_options.merge(options)
+      opts = default_options.merge(options)
 
       input = if opts[:memoize]
-        MemoizingInput.new(string)
+        MemoizedInput.new(string)
       else
         Input.new(string)
       end
@@ -551,18 +567,13 @@ module Citrus
       Match.new(string.slice(opts[:offset], length), events)
     end
 
-    # The default set of options to use when parsing.
-    def default_parse_options # :nodoc:
-      { :offset   => 0,
-        :memoize  => false,
-        :consume  => true
-      }
-    end
-
     # Tests whether or not this rule matches on the given +string+. Returns the
-    # length of the match if any can be made, +nil+ otherwise.
-    def test(string)
-      Input.new(string).test(self)
+    # length of the match if any can be made, +nil+ otherwise. Accepts the same
+    # +options+ as #parse.
+    def test(string, options={})
+      parse(string, options).length
+    rescue ParseError
+      nil
     end
 
     # Returns +true+ if this rule is a Terminal.
@@ -1027,7 +1038,7 @@ module Citrus
         events << CLOSE
         events << length
       else
-        events.slice!(start, events.size)
+        events.slice!(start, index)
       end
 
       events
@@ -1088,7 +1099,7 @@ module Citrus
         events << CLOSE
         events << length
       else
-        events.slice!(start, events.size)
+        events.slice!(start, index)
       end
 
       events
@@ -1380,6 +1391,6 @@ class Object
     namespace = respond_to?(:const_set) ? self : Object
     namespace.const_set(name, Citrus::Grammar.new(&block))
   rescue NameError
-    raise ArgumentError, 'Invalid grammar name: %s' % name
+    raise ArgumentError, "Invalid grammar name: #{name}"
   end
 end

data/test/input_test.rb

@@ -2,8 +2,7 @@ require File.expand_path('../helper', __FILE__)
 
 class InputTest < Test::Unit::TestCase
   def test_memoized?
-    assert !Input.new('').memoized?
-    assert MemoizingInput.new('').memoized?
+    assert_equal(false, Input.new('').memoized?)
   end
 
   def test_offsets_new
@@ -23,7 +22,7 @@ class InputTest < Test::Unit::TestCase
     assert_equal("def\n", input.line)
   end
 
-  def test_events
+  def test_exec
     a = Rule.for('a')
     b = Rule.for('b')
     c = Rule.for('c')
@@ -56,7 +55,7 @@ class InputTest < Test::Unit::TestCase
     assert_equal(expected_events, events)
   end
 
-  def test_events2
+  def test_exec2
     a = Rule.for('a')
     b = Rule.for('b')
     c = Choice.new([ a, b ])
@@ -100,89 +99,4 @@ class InputTest < Test::Unit::TestCase
 
     assert_equal(expected_events, events)
   end
-
-  grammar :LetterA do
-    rule :top do
-      any(:three_as, :two_as, :one_a)
-    end
-
-    rule :three_as do
-      rep(:one_a, 3, 3)
-    end
-
-    rule :two_as do
-      rep(:one_a, 2, 2)
-    end
-
-    rule :one_a do
-      "a"
-    end
-  end
-
-  def test_cache_hits1
-    input = MemoizingInput.new('a')
-    input.exec(LetterA.rule(:top))
-    assert_equal(3, input.cache_hits)
-  end
-
-  def test_cache_hits2
-    input = MemoizingInput.new('aa')
-    input.exec(LetterA.rule(:top))
-    assert_equal(2, input.cache_hits)
-  end
-
-  def test_cache_hits3
-    input = MemoizingInput.new('aaa')
-    input.exec(LetterA.rule(:top))
-    assert_equal(0, input.cache_hits)
-  end
-
-  grammar :Addition do
-    rule :additive do
-      all(:number, :plus, label(any(:additive, :number), 'term')) {
-        number.value + term.value
-      }
-    end
-
-    rule :number do
-      all(/[0-9]+/, :space) {
-        strip.to_i
-      }
-    end
-
-    rule :plus do
-      all('+', :space)
-    end
-
-    rule :space do
-      /[ \t]*/
-    end
-  end
-
-  def test_match
-    match = Addition.parse('+', :root => :plus)
-    assert(match)
-    assert(match.matches)
-    assert_equal(2, match.matches.length)
-
-    match = Addition.parse('+ ', :root => :plus)
-    assert(match)
-    assert(match.matches)
-    assert_equal(2, match.matches.length)
-
-    match = Addition.parse('99', :root => :number)
-    assert(match)
-    assert(match.matches)
-    assert_equal(2, match.matches.length)
-
-    match = Addition.parse('99 ', :root => :number)
-    assert(match)
-    assert(match.matches)
-    assert_equal(2, match.matches.length)
-
-    match = Addition.parse('1+2')
-    assert(match)
-    assert(match.matches)
-    assert_equal(3, match.matches.length)
-  end
 end

data/test/match_test.rb

@@ -67,4 +67,53 @@ class MatchTest < Test::Unit::TestCase
       assert_equal(3, m.matches.length)
     end
   end
+
+  grammar :Addition do
+    rule :additive do
+      all(:number, :plus, label(any(:additive, :number), 'term')) {
+        number.value + term.value
+      }
+    end
+
+    rule :number do
+      all(/[0-9]+/, :space) {
+        strip.to_i
+      }
+    end
+
+    rule :plus do
+      all('+', :space)
+    end
+
+    rule :space do
+      /[ \t]*/
+    end
+  end
+
+  def test_matches2
+    match = Addition.parse('+', :root => :plus)
+    assert(match)
+    assert(match.matches)
+    assert_equal(2, match.matches.length)
+
+    match = Addition.parse('+ ', :root => :plus)
+    assert(match)
+    assert(match.matches)
+    assert_equal(2, match.matches.length)
+
+    match = Addition.parse('99', :root => :number)
+    assert(match)
+    assert(match.matches)
+    assert_equal(2, match.matches.length)
+
+    match = Addition.parse('99 ', :root => :number)
+    assert(match)
+    assert(match.matches)
+    assert_equal(2, match.matches.length)
+
+    match = Addition.parse('1+2')
+    assert(match)
+    assert(match.matches)
+    assert_equal(3, match.matches.length)
+  end
 end

data/test/memoized_input_test.rb

@@ -0,0 +1,43 @@
+require File.expand_path('../helper', __FILE__)
+
+class MemoizedInputTest < Test::Unit::TestCase
+  def test_memoized?
+    assert MemoizedInput.new('').memoized?
+  end
+
+  grammar :LetterA do
+    rule :top do
+      any(:three_as, :two_as, :one_a)
+    end
+
+    rule :three_as do
+      rep(:one_a, 3, 3)
+    end
+
+    rule :two_as do
+      rep(:one_a, 2, 2)
+    end
+
+    rule :one_a do
+      "a"
+    end
+  end
+
+  def test_cache_hits1
+    input = MemoizedInput.new('a')
+    input.exec(LetterA.rule(:top))
+    assert_equal(3, input.cache_hits)
+  end
+
+  def test_cache_hits2
+    input = MemoizedInput.new('aa')
+    input.exec(LetterA.rule(:top))
+    assert_equal(2, input.cache_hits)
+  end
+
+  def test_cache_hits3
+    input = MemoizedInput.new('aaa')
+    input.exec(LetterA.rule(:top))
+    assert_equal(0, input.cache_hits)
+  end
+end

metadata

@@ -3,33 +3,32 @@ name: citrus
 version: !ruby/object:Gem::Version 
   prerelease: false
   segments: 
-  - 2
-  - 3
-  - 1
-  version: 2.3.1
+    - 2
+    - 3
+    - 2
+  version: 2.3.2
 platform: ruby
 authors: 
-- Michael Jackson
+  - Michael Jackson
 autorequire: 
 bindir: bin
 cert_chain: []
 
-date: 2010-12-31 00:00:00 -08:00
+date: 2011-01-02 00:00:00 -08:00
 default_executable: 
 dependencies: 
-- !ruby/object:Gem::Dependency 
-  name: rake
-  prerelease: false
-  requirement: &id001 !ruby/object:Gem::Requirement 
-    none: false
-    requirements: 
-    - - ">="
-      - !ruby/object:Gem::Version 
-        segments: 
-        - 0
-        version: "0"
-  type: :development
-  version_requirements: *id001
+  - !ruby/object:Gem::Dependency 
+    name: rake
+    prerelease: false
+    requirement: &id001 !ruby/object:Gem::Requirement 
+      requirements: 
+        - - ">="
+          - !ruby/object:Gem::Version 
+            segments: 
+              - 0
+            version: "0"
+    type: :development
+    version_requirements: *id001
 description: Parsing Expressions for Ruby
 email: mjijackson@gmail.com
 executables: []
@@ -37,112 +36,112 @@ executables: []
 extensions: []
 
 extra_rdoc_files: 
-- README
+  - README
 files: 
-- benchmark/seqpar.citrus
-- benchmark/seqpar.gnuplot
-- benchmark/seqpar.rb
-- doc/background.markdown
-- doc/example.markdown
-- doc/extras.markdown
-- doc/index.markdown
-- doc/license.markdown
-- doc/links.markdown
-- doc/syntax.markdown
-- doc/testing.markdown
-- examples/calc.citrus
-- examples/calc.rb
-- examples/ip.citrus
-- examples/ip.rb
-- lib/citrus/file.rb
-- lib/citrus.rb
-- test/_files/alias.citrus
-- test/_files/grammar1.citrus
-- test/_files/grammar2.citrus
-- test/_files/rule1.citrus
-- test/_files/rule2.citrus
-- test/_files/rule3.citrus
-- test/_files/super.citrus
-- test/_files/super2.citrus
-- test/alias_test.rb
-- test/and_predicate_test.rb
-- test/but_predicate_test.rb
-- test/calc_file_test.rb
-- test/calc_test.rb
-- test/choice_test.rb
-- test/extension_test.rb
-- test/file_test.rb
-- test/grammar_test.rb
-- test/helper.rb
-- test/input_test.rb
-- test/label_test.rb
-- test/match_test.rb
-- test/multibyte_test.rb
-- test/not_predicate_test.rb
-- test/parse_error_test.rb
-- test/repeat_test.rb
-- test/sequence_test.rb
-- test/string_terminal_test.rb
-- test/super_test.rb
-- test/terminal_test.rb
-- citrus.gemspec
-- Rakefile
-- README
+  - benchmark/seqpar.citrus
+  - benchmark/seqpar.gnuplot
+  - benchmark/seqpar.rb
+  - doc/background.markdown
+  - doc/example.markdown
+  - doc/extras.markdown
+  - doc/index.markdown
+  - doc/license.markdown
+  - doc/links.markdown
+  - doc/syntax.markdown
+  - doc/testing.markdown
+  - examples/calc.citrus
+  - examples/calc.rb
+  - examples/ip.citrus
+  - examples/ip.rb
+  - lib/citrus.rb
+  - lib/citrus/file.rb
+  - test/alias_test.rb
+  - test/and_predicate_test.rb
+  - test/but_predicate_test.rb
+  - test/calc_file_test.rb
+  - test/calc_test.rb
+  - test/choice_test.rb
+  - test/extension_test.rb
+  - test/file_test.rb
+  - test/grammar_test.rb
+  - test/helper.rb
+  - test/input_test.rb
+  - test/label_test.rb
+  - test/match_test.rb
+  - test/memoized_input_test.rb
+  - test/multibyte_test.rb
+  - test/not_predicate_test.rb
+  - test/parse_error_test.rb
+  - test/repeat_test.rb
+  - test/sequence_test.rb
+  - test/string_terminal_test.rb
+  - test/super_test.rb
+  - test/terminal_test.rb
+  - test/_files/alias.citrus
+  - test/_files/grammar1.citrus
+  - test/_files/grammar2.citrus
+  - test/_files/rule1.citrus
+  - test/_files/rule2.citrus
+  - test/_files/rule3.citrus
+  - test/_files/super.citrus
+  - test/_files/super2.citrus
+  - citrus.gemspec
+  - Rakefile
+  - README
 has_rdoc: true
 homepage: http://mjijackson.com/citrus
 licenses: []
 
 post_install_message: 
 rdoc_options: 
-- --line-numbers
-- --inline-source
-- --title
-- Citrus
-- --main
-- Citrus
+  - --line-numbers
+  - --inline-source
+  - --title
+  - Citrus
+  - --main
+  - Citrus
 require_paths: 
-- lib
+  - lib
 required_ruby_version: !ruby/object:Gem::Requirement 
-  none: false
   requirements: 
-  - - ">="
-    - !ruby/object:Gem::Version 
-      segments: 
-      - 0
-      version: "0"
+    - - ">="
+      - !ruby/object:Gem::Version 
+        segments: 
+          - 0
+        version: "0"
 required_rubygems_version: !ruby/object:Gem::Requirement 
-  none: false
   requirements: 
-  - - ">="
-    - !ruby/object:Gem::Version 
-      segments: 
-      - 0
-      version: "0"
+    - - ">="
+      - !ruby/object:Gem::Version 
+        segments: 
+          - 0
+        version: "0"
 requirements: []
 
 rubyforge_project: 
-rubygems_version: 1.3.7
+rubygems_version: 1.3.6
 signing_key: 
 specification_version: 3
 summary: Parsing Expressions for Ruby
 test_files: 
-- test/alias_test.rb
-- test/and_predicate_test.rb
-- test/but_predicate_test.rb
-- test/calc_file_test.rb
-- test/calc_test.rb
-- test/choice_test.rb
-- test/extension_test.rb
-- test/file_test.rb
-- test/grammar_test.rb
-- test/input_test.rb
-- test/label_test.rb
-- test/match_test.rb
-- test/multibyte_test.rb
-- test/not_predicate_test.rb
-- test/parse_error_test.rb
-- test/repeat_test.rb
-- test/sequence_test.rb
-- test/string_terminal_test.rb
-- test/super_test.rb
-- test/terminal_test.rb
+  - test/alias_test.rb
+  - test/and_predicate_test.rb
+  - test/but_predicate_test.rb
+  - test/calc_file_test.rb
+  - test/calc_test.rb
+  - test/choice_test.rb
+  - test/extension_test.rb
+  - test/file_test.rb
+  - test/grammar_test.rb
+  - test/input_test.rb
+  - test/label_test.rb
+  - test/match_test.rb
+  - test/memoized_input_test.rb
+  - test/multibyte_test.rb
+  - test/not_predicate_test.rb
+  - test/parse_error_test.rb
+  - test/repeat_test.rb
+  - test/sequence_test.rb
+  - test/string_terminal_test.rb
+  - test/super_test.rb
+  - test/terminal_test.rb