citrus 2.4.1 → 2.5.0

data/CHANGES

@@ -1,3 +1,16 @@
+= 2.5.0 / 2014-03-13
+
+  * Inputs may be generated from many different sources, including Pathname and
+    IO objects (thanks blambeau).
+
+  * Matches keep track of their offset in the original source  (thanks
+    blambeau).
+
+  * Citrus.load no longer raises Citrus::LoadError for files that can't be found
+    or are not readable. Users must rescue Errno::ENOENT instead, for example.
+
+  * Removed a few ruby warnings (thanks tbuehlmann)
+
 = 2.4.1 / 2011-11-04
 
   * Fixed a bug that prevented rule names from starting with "super".

data/Rakefile

@@ -15,7 +15,7 @@ desc "Generate API documentation"
 task :api => 'lib/citrus.rb' do |t|
   output_dir = ENV['OUTPUT_DIR'] || 'api'
   rm_rf output_dir
-  sh((<<-SH).gsub(/[\s\n]+/, ' ').strip)
+  sh((<<-SH).gsub(/\s+/, ' ').strip)
   hanna
     --op #{output_dir}
     --promiscuous

data/lib/citrus.rb

@@ -73,9 +73,6 @@ module Citrus
     force = options.delete(:force)
 
     if force || !cache[file]
-      raise LoadError, "Cannot find file #{file}" unless ::File.file?(file)
-      raise LoadError, "Cannot read file #{file}" unless ::File.readable?(file)
-
       begin
         cache[file] = eval(::File.read(file), options)
       rescue SyntaxError => e
@@ -117,7 +114,10 @@ module Citrus
   end
 
   # A base class for all Citrus errors.
-  class Error < RuntimeError; end
+  class Error < StandardError; end
+
+  # Raised when Citrus.require can't find the file to load.
+  class LoadError < Error; end
 
   # Raised when a parse fails.
   class ParseError < Error
@@ -156,9 +156,6 @@ module Citrus
     end
   end
 
-  # Raised when Citrus.load fails to load a file.
-  class LoadError < Error; end
-
   # Raised when Citrus::File.parse fails.
   class SyntaxError < Error
     # The +error+ given here is an instance of Citrus::ParseError.
@@ -173,14 +170,19 @@ module Citrus
   # An Input is a scanner that is responsible for executing rules at different
   # positions in the input string and persisting event streams.
   class Input < StringScanner
-    def initialize(string)
-      super(string)
+    def initialize(source)
+      super(source_text(source))
+      @source = source
       @max_offset = 0
     end
 
     # The maximum offset in the input that was successfully parsed.
     attr_reader :max_offset
 
+    # The initial source passed at construction. Typically a String
+    # or a Pathname.
+    attr_reader :source
+
     def reset # :nodoc:
       @max_offset = 0
       super
@@ -263,8 +265,24 @@ module Citrus
       events[-1]
     end
 
+    # Returns the scanned string.
+    alias_method :to_str, :string
+
   private
 
+    # Returns the text to parse from +source+.
+    def source_text(source)
+      if source.respond_to?(:to_path)
+        ::File.read(source.to_path)
+      elsif source.respond_to?(:read)
+        source.read
+      elsif source.respond_to?(:to_str)
+        source.to_str
+      else
+        raise ArgumentError, "Unable to parse from #{source}", caller
+      end
+    end
+
     # Appends all events for +rule+ at the given +position+ to +events+.
     def apply_rule(rule, position, events)
       rule.exec(self, events)
@@ -361,17 +379,24 @@ module Citrus
       super
     end
 
-    # Parses the given +string+ using this grammar's root rule. Accepts the same
+    # Parses the given +source+ using this grammar's root rule. Accepts the same
     # +options+ as Rule#parse, plus the following:
     #
     # root::    The name of the root rule to start parsing at. Defaults to this
     #           grammar's #root.
-    def parse(string, options={})
+    def parse(source, options={})
       rule_name = options.delete(:root) || root
       raise Error, "No root rule specified" unless rule_name
       rule = rule(rule_name)
       raise Error, "No rule named \"#{rule_name}\"" unless rule
-      rule.parse(string, options)
+      rule.parse(source, options)
+    end
+
+    # Parses the contents of the file at the given +path+ using this grammar's
+    # #root rule. Accepts the same +options+ as #parse.
+    def parse_file(path, options={})
+      path = Pathname.new(path.to_str) unless Pathname === path
+      parse(path, options)
     end
 
     # Returns the name of this grammar as a string.
@@ -455,9 +480,16 @@ module Citrus
     # Gets/sets the +name+ of the root rule of this grammar. If no root rule is
     # explicitly specified, the name of this grammar's first rule is returned.
     def root(name=nil)
-      @root = name.to_sym if name
-      # The first rule in a grammar is the default root.
-      @root || rule_names.first
+      if name
+        @root = name.to_sym
+      else
+        # The first rule in a grammar is the default root.
+        if instance_variable_defined?(:@root)
+          @root
+        else
+          rule_names.first
+        end
+      end
     end
 
     # Creates a new rule that will match any single character. A block may be
@@ -623,10 +655,11 @@ module Citrus
     #             +false+.
     # offset::    The offset in +string+ at which to start parsing. Defaults
     #             to 0.
-    def parse(string, options={})
+    def parse(source, options={})
       opts = default_options.merge(options)
 
-      input = (opts[:memoize] ? MemoizedInput : Input).new(string)
+      input = (opts[:memoize] ? MemoizedInput : Input).new(source)
+      string = input.string
       input.pos = opts[:offset] if opts[:offset] > 0
 
       events = input.exec(self)
@@ -636,7 +669,7 @@ module Citrus
         raise ParseError, input
       end
 
-      Match.new(string.slice(opts[:offset], length), events)
+      Match.new(input, events, opts[:offset])
     end
 
     # Tests whether or not this rule matches on the given +string+. Returns the
@@ -1239,14 +1272,13 @@ module Citrus
   # instantiated as needed. This class provides several convenient tree
   # traversal methods that help when examining and interpreting parse results.
   class Match
-    def initialize(string, events=[])
-      @string = string
+    def initialize(input, events=[], offset=0)
+      @input = input
+      @offset = offset
+      @captures = nil
+      @matches = nil
 
       if events.length > 0
-        if events[-1] != string.length
-          raise ArgumentError, "Invalid events for length #{string.length}"
-        end
-
         elisions = []
 
         while events[0].elide?
@@ -1261,18 +1293,35 @@ module Citrus
         end
       else
         # Create a default stream of events for the given string.
+        string = input.to_str
         events = [Rule.for(string), CLOSE, string.length]
       end
 
       @events = events
     end
 
+    # The original Input this Match was generated on.
+    attr_reader :input
+
+    # The index of this match in the #input.
+    attr_reader :offset
+
     # The array of events for this match.
     attr_reader :events
 
     # Returns the length of this match.
     def length
-      @string.length
+      events.last
+    end
+
+    # Convenient shortcut for +input.source+
+    def source
+      (input.respond_to?(:source) && input.source) || input
+    end
+
+    # Returns the slice of the source text that this match captures.
+    def string
+      @string ||= input.to_str[offset, length]
     end
 
     # Returns a hash of capture names to arrays of matches with that name,
@@ -1296,16 +1345,18 @@ module Citrus
     # Allows methods of this match's string to be called directly and provides
     # a convenient interface for retrieving the first match with a given name.
     def method_missing(sym, *args, &block)
-      if @string.respond_to?(sym)
-        @string.__send__(sym, *args, &block)
+      unless defined?(Citrus::METHOD_MISSING_WARNED)
+        warn("[`#{sym}`] Citrus::Match#method_missing is unsafe and will be removed in 3.0. Use captures.")
+        Citrus.send(:const_set, :METHOD_MISSING_WARNED, true)
+      end
+      if string.respond_to?(sym)
+        string.__send__(sym, *args, &block)
       else
         captures[sym].first
       end
     end
 
-    def to_s
-      @string
-    end
+    alias_method :to_s, :string
 
     # This alias allows strings to be compared to the string value of Match
     # objects. It is most useful in assertions in unit tests, e.g.:
@@ -1339,9 +1390,9 @@ module Citrus
     def ==(other)
       case other
       when String
-        @string == other
+        string == other
       when Match
-        @string == other.to_s
+        string == other.to_s
       else
         super
       end
@@ -1350,7 +1401,7 @@ module Citrus
     alias_method :eql?, :==
 
     def inspect
-      @string.inspect
+      string.inspect
     end
 
     # Prints the entire subtree of this match using the given +indent+ to
@@ -1372,7 +1423,7 @@ module Citrus
           rule = stack.pop
 
           space = indent * (stack.size / 3)
-          string = @string.slice(os, event)
+          string = self.string.slice(os, event)
           lines[start] = "#{space}#{string.inspect} rule=#{rule}, offset=#{os}, length=#{event}"
 
           last_length = event unless last_length
@@ -1425,7 +1476,7 @@ module Citrus
             os = stack.pop
             start = stack.pop
 
-            match = Match.new(@string.slice(os, event), @events[start..index])
+            match = Match.new(input, @events[start..index], @offset + os)
             capture!(rule, match)
 
             if stack.size == 1
@@ -1518,6 +1569,7 @@ class Object
   #     end
   #
   def grammar(name, &block)
+    warn("Object#grammar will no longer be available by default in citrus 3.0; You should require 'citrus/core_ext'.")
     namespace = respond_to?(:const_set) ? self : Object
     namespace.const_set(name, Citrus::Grammar.new(&block))
   rescue NameError

data/lib/citrus/file.rb

@@ -165,7 +165,7 @@ module Citrus
     end
 
     rule :super do
-      all('super', andp(" "), :space) {
+      ext(:super_keyword) {
         Super.new
       }
     end
@@ -329,6 +329,7 @@ module Citrus
     rule :grammar_keyword,  [ /\bgrammar\b/, :space ]
     rule :root_keyword,     [ /\broot\b/, :space ]
     rule :rule_keyword,     [ /\brule\b/, :space ]
+    rule :super_keyword,    [ /\bsuper\b/, :space ]
     rule :end_keyword,      [ /\bend\b/, :space ]
 
     rule :constant,         /[A-Z][a-zA-Z0-9_]*/

data/lib/citrus/version.rb

@@ -1,6 +1,6 @@
 module Citrus
   # The current version of Citrus as [major, minor, patch].
-  VERSION = [2, 4, 1]
+  VERSION = [2, 5, 0]
 
   # Returns the current version of Citrus as a string.
   def self.version

data/test/_files/rule6.citrus

@@ -0,0 +1 @@
+rule super end

data/test/_files/rule7.citrus

@@ -0,0 +1,3 @@
+rule abc
+  "abc" | super
+end

data/test/alias_test.rb

@@ -12,7 +12,6 @@ class AliasTest < Test::Unit::TestCase
       rule :b, 'abc'
     }
     rule_a = grammar.rule(:a)
-    rule_b = grammar.rule(:b)
     events = rule_a.exec(Input.new('abc'))
     assert_equal([rule_a, CLOSE, 3], events)
   end
@@ -36,7 +35,6 @@ class AliasTest < Test::Unit::TestCase
       rule :b, :a
     }
     rule_b2 = grammar2.rule(:b)
-    rule_a1 = grammar1.rule(:a)
     events = rule_b2.exec(Input.new('abc'))
     assert_equal([rule_b2, CLOSE, 3], events)
   end

data/test/grammar_test.rb

@@ -74,7 +74,7 @@ class GrammarTest < Test::Unit::TestCase
       rule(:num) { all(1, 2, 3) }
     }
     assert_raise ParseError do
-      match = grammar.parse('12')
+      grammar.parse('12')
     end
   end
 
@@ -99,7 +99,7 @@ class GrammarTest < Test::Unit::TestCase
       rule(:alphanum) { any(/[a-z]/, 0..9) }
     }
     assert_raise ParseError do
-      match = grammar.parse('A')
+      grammar.parse('A')
     end
   end
 
@@ -126,6 +126,29 @@ class GrammarTest < Test::Unit::TestCase
     assert_equal(str.length, match.length)
   end
 
+  def test_parse_file
+    grammar = Grammar.new {
+      rule("words"){ rep(any(" ", /[a-z]+/)) }
+    }
+
+    require 'tempfile'
+    Tempfile.open('citrus') do |tmp|
+      tmp << "abd def"
+      tmp.close
+
+      match = grammar.parse_file(tmp.path)
+
+      assert(match)
+      assert_instance_of(Input, match.input)
+      assert_instance_of(Pathname, match.source)
+
+      match.matches.each do |m|
+        assert_instance_of(Input, m.input)
+        assert_instance_of(Pathname, m.source)
+      end
+    end
+  end
+
   def test_global_grammar
     assert_raise ArgumentError do
       grammar(:abc)

data/test/input_test.rb

@@ -1,6 +1,21 @@
 require File.expand_path('../helper', __FILE__)
 
 class InputTest < Test::Unit::TestCase
+  def test_new
+    # to_str
+    assert_equal('abc', Input.new('abc').string)
+
+    # read
+    selftext = ::File.read(__FILE__)
+    ::File.open(__FILE__, 'r') do |io|
+      assert_equal(selftext, Input.new(io).string)
+    end
+
+    # to_path
+    path = Struct.new(:to_path).new(__FILE__)
+    assert_equal(selftext, Input.new(path).string)
+  end
+
   def test_memoized?
     assert_equal(false, Input.new('').memoized?)
   end

data/test/match_test.rb

@@ -20,6 +20,23 @@ class MatchTest < Test::Unit::TestCase
     assert_equal(false, match2 == match1)
   end
 
+  def test_source
+    match1 = Match.new('abcdef')
+    assert_equal 'abcdef', match1.source
+
+    path   = Struct.new(:to_path).new(__FILE__)
+    match2 = Match.new(Input.new(path))
+    assert_equal path, match2.source
+  end
+
+  def test_string
+    match1 = Match.new('abcdef')
+    assert_equal 'abcdef', match1.string
+
+    match2 = Match.new('abcdef', [Rule.for('bcd'), -1, 3], 1)
+    assert_equal 'bcd', match2.string
+  end
+
   def test_matches
     a = Rule.for('a')
     b = Rule.for('b')
@@ -59,11 +76,18 @@ class MatchTest < Test::Unit::TestCase
       CLOSE, 3
     ]
 
-    match.matches.each do |m|
+    match.matches.each_with_index do |m, i|
       assert_equal(sub_events, m.events)
+      assert_equal(i*3, m.offset)
+      assert_equal(3, m.length)
+      assert_equal("abc", m.string)
       assert_equal("abc", m)
       assert(m.matches)
       assert_equal(3, m.matches.length)
+      m.matches.each_with_index do |m2,i2|
+        assert_equal(i*3+i2, m2.offset)
+        assert_equal(1, m2.length)
+      end
     end
   end
 

data/test/super_test.rb

@@ -18,7 +18,6 @@ class SuperTest < Test::Unit::TestCase
     rule_2a = grammar2.rule(:a)
     rule_2a_als = rule_2a.rules[0]
     rule_2a_sup = rule_2a.rules[1]
-    rule_1a = grammar1.rule(:a)
 
     events = rule_2a.exec(Input.new('abc'))
     assert_equal([
@@ -58,12 +57,9 @@ class SuperTest < Test::Unit::TestCase
       rule :a, any(sup, :b)
       rule :b, sup
     }
-    rule_1a = grammar1.rule(:a)
-    rule_1b = grammar1.rule(:b)
     rule_2a = grammar2.rule(:a)
     rule_2a_sup = rule_2a.rules[0]
     rule_2a_als = rule_2a.rules[1]
-    rule_2b = grammar2.rule(:b)
 
     events = rule_2a.exec(Input.new('abc'))
     assert_equal([

metadata

@@ -1,47 +1,40 @@
---- !ruby/object:Gem::Specification 
+--- !ruby/object:Gem::Specification
 name: citrus
-version: !ruby/object:Gem::Version 
-  hash: 29
+version: !ruby/object:Gem::Version
+  version: 2.5.0
   prerelease: 
-  segments: 
-  - 2
-  - 4
-  - 1
-  version: 2.4.1
 platform: ruby
-authors: 
+authors:
 - Michael Jackson
 autorequire: 
 bindir: bin
 cert_chain: []
-
-date: 2011-11-04 00:00:00 -07:00
-default_executable: 
-dependencies: 
-- !ruby/object:Gem::Dependency 
+date: 2014-03-14 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
   name: rake
-  prerelease: false
-  requirement: &id001 !ruby/object:Gem::Requirement 
+  requirement: !ruby/object:Gem::Requirement
     none: false
-    requirements: 
-    - - ">="
-      - !ruby/object:Gem::Version 
-        hash: 3
-        segments: 
-        - 0
-        version: "0"
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
   type: :development
-  version_requirements: *id001
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
 description: Parsing Expressions for Ruby
 email: mjijackson@gmail.com
 executables: []
-
 extensions: []
-
-extra_rdoc_files: 
+extra_rdoc_files:
 - README.md
 - CHANGES
-files: 
+files:
 - benchmark/seqpar.citrus
 - benchmark/seqpar.gnuplot
 - benchmark/seqpar.rb
@@ -69,6 +62,8 @@ files:
 - test/_files/rule3.citrus
 - test/_files/rule4.citrus
 - test/_files/rule5.citrus
+- test/_files/rule6.citrus
+- test/_files/rule7.citrus
 - test/alias_test.rb
 - test/and_predicate_test.rb
 - test/but_predicate_test.rb
@@ -99,46 +94,37 @@ files:
 - Rakefile
 - README.md
 - CHANGES
-has_rdoc: true
 homepage: http://mjijackson.com/citrus
 licenses: []
-
 post_install_message: 
-rdoc_options: 
+rdoc_options:
 - --line-numbers
 - --inline-source
 - --title
 - Citrus
 - --main
 - Citrus
-require_paths: 
+require_paths:
 - lib
-required_ruby_version: !ruby/object:Gem::Requirement 
+required_ruby_version: !ruby/object:Gem::Requirement
   none: false
-  requirements: 
-  - - ">="
-    - !ruby/object:Gem::Version 
-      hash: 3
-      segments: 
-      - 0
-      version: "0"
-required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
   none: false
-  requirements: 
-  - - ">="
-    - !ruby/object:Gem::Version 
-      hash: 3
-      segments: 
-      - 0
-      version: "0"
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
 requirements: []
-
 rubyforge_project: 
-rubygems_version: 1.6.2
+rubygems_version: 1.8.23
 signing_key: 
 specification_version: 3
 summary: Parsing Expressions for Ruby
-test_files: 
+test_files:
 - test/alias_test.rb
 - test/and_predicate_test.rb
 - test/but_predicate_test.rb