re2 0.3.0 → 0.4.0

data/lib/re2/string.rb

@@ -0,0 +1,100 @@
+# re2 (http://github.com/mudge/re2)
+# Ruby bindings to re2, an "efficient, principled regular expression library"
+#
+# Copyright (c) 2010-2012, Paul Mucur (http://mudge.name)
+# Released under the BSD Licence, please see LICENSE.txt
+
+require "re2"
+
+module RE2
+  module String
+
+    # Replaces the first occurrence +pattern+ with +rewrite+ <i>in place</i>.
+    #
+    # @param [String, RE2::Regexp] pattern a regexp matching text to be replaced
+    # @param [String] rewrite the string to replace with
+    # @example
+    #   "hello there".re2_sub("hello", "howdy") #=> "howdy there"
+    #   re2 = RE2.new("hel+o")
+    #   "hello there".re2_sub(re2, "yo")        #=> "yo there"
+    #   text = "Good morning"
+    #   text.re2_sub("morn", "even")            #=> "Good evening"
+    #   text                                    #=> "Good evening"
+    def re2_sub(*args)
+      RE2.Replace(self, *args)
+    end
+
+    # Replaces every occurrence of +pattern+ with +rewrite+ <i>in place</i>.
+    #
+    # @param [String, RE2::Regexp] pattern a regexp matching text to be replaced
+    # @param [String] rewrite the string to replace with
+    # @example
+    #   "hello there".re2_gsub("e", "i")   #=> "hillo thiri"
+    #   re2 = RE2.new("oo?")
+    #   "whoops-doops".re2_gsub(re2, "e")  #=> "wheps-deps"
+    #   text = "Good morning"
+    #   text.re2_gsub("o", "ee")           #=> "Geeeed meerning"
+    #   text                               #=> "Geeeed meerning"
+    def re2_gsub(*args)
+      RE2.GlobalReplace(self, *args)
+    end
+
+    # Match the pattern and return either a boolean (if no submatches are required)
+    # or a {RE2::MatchData} instance.
+    #
+    # @return [Boolean, RE2::MatchData]
+    #
+    # @overload match(pattern)
+    #   Returns an {RE2::MatchData} containing the matching
+    #   pattern and all subpatterns resulting from looking for
+    #   +pattern+.
+    #
+    #   @param [String, RE2::Regexp] pattern the regular expression to match
+    #   @return [RE2::MatchData] the matches
+    #   @raise [NoMemoryError] if there was not enough memory to allocate the matches
+    #   @example
+    #     r = RE2::Regexp.new('w(o)(o)')
+    #     "woo".re2_match(r)             #=> #<RE2::MatchData "woo" 1:"o" 2:"o">
+    #
+    # @overload match(pattern, 0)
+    #   Returns either true or false indicating whether a
+    #   successful match was made.
+    #
+    #   @param [String, RE2::Regexp] pattern the regular expression to match
+    #   @return [Boolean] whether the match was successful
+    #   @raise [NoMemoryError] if there was not enough memory to allocate the matches
+    #   @example
+    #     r = RE2::Regexp.new('w(o)(o)')
+    #     "woo".re2_match(0) #=> true
+    #     "bob".re2_match(0) #=> false
+    #
+    # @overload match(pattern, number_of_matches)
+    #   See +match(pattern)+ but with a specific number of
+    #   matches returned (padded with nils if necessary).
+    #
+    #   @param [String, RE2::Regexp] pattern the regular expression to match
+    #   @param [Fixnum] number_of_matches the number of matches to return
+    #   @return [RE2::MatchData] the matches
+    #   @raise [NoMemoryError] if there was not enough memory to allocate the matches
+    #   @example
+    #     r = RE2::Regexp.new('w(o)(o)')
+    #     "woo".re2_match(r, 1) #=> #<RE2::MatchData "woo" 1:"o">
+    #     "woo".re2_match(r, 3) #=> #<RE2::MatchData "woo" 1:"o" 2:"o" 3:nil>
+    def re2_match(pattern, *args)
+      RE2::Regexp.new(pattern).match(self, *args)
+    end
+
+    # Escapes all potentially meaningful regexp characters.
+    # The returned string, used as a regular expression, will exactly match the
+    # original string.
+    #
+    # @return [String] the escaped string
+    # @example
+    #   "1.5-2.0?".escape    #=> "1\.5\-2\.0\?"
+    def re2_escape
+      RE2.QuoteMeta(self)
+    end
+
+    alias_method :re2_quote, :re2_escape
+  end
+end

data/spec/kernel_spec.rb

@@ -0,0 +1,15 @@
+require "spec_helper"
+
+describe Kernel do
+  describe "#RE2" do
+    it "returns an RE2::Regexp instance given a pattern" do
+      RE2('w(o)(o)').must_be_instance_of(RE2::Regexp)
+    end
+
+    it "returns an RE2::Regexp instance given a pattern and options" do
+      re = RE2('w(o)(o)', :case_sensitive => false)
+      re.must_be_instance_of(RE2::Regexp)
+      re.wont_be(:case_sensitive?)
+    end
+  end
+end

data/spec/re2/match_data_spec.rb

@@ -0,0 +1,141 @@
+require "spec_helper"
+
+describe RE2::MatchData do
+
+  describe "#to_a" do
+    it "is populated with the match and capturing groups" do
+      a = RE2::Regexp.new('w(o)(o)').match('woo').to_a
+      a.must_equal(["woo", "o", "o"])
+    end
+
+    it "populates optional capturing groups with nil if they are missing" do
+      a = RE2::Regexp.new('(\d?)(a)(b)').match('ab').to_a
+      a.must_equal(["ab", nil, "a", "b"])
+    end
+  end
+
+  describe "#[]" do
+    it "accesses capturing groups by numerical index" do
+      md = RE2::Regexp.new('(\d)(\d{2})').match("123")
+      md[1].must_equal("1")
+      md[2].must_equal("23")
+    end
+
+    it "has the whole match as the 0th item" do
+      md = RE2::Regexp.new('(\d)(\d{2})').match("123")
+      md[0].must_equal("123")
+    end
+
+    it "supports access by numerical ranges" do
+      md = RE2::Regexp.new('(\d+) (\d+) (\d+)').match("123 456 789")
+      md[1..3].must_equal(["123", "456", "789"])
+      md[1...3].must_equal(["123", "456"])
+    end
+
+    it "supports slicing" do
+      md = RE2::Regexp.new('(\d+) (\d+) (\d+)').match("123 456 789")
+      md[1, 3].must_equal(["123", "456", "789"])
+      md[1, 2].must_equal(["123", "456"])
+    end
+
+    it "returns nil if attempting to access non-existent capturing groups by index" do
+      md = RE2::Regexp.new('(\d+)').match('bob 123')
+      md[2].must_be_nil
+      md[3].must_be_nil
+    end
+
+    it "allows access by string names when there are named groups" do
+      md = RE2::Regexp.new('(?P<numbers>\d+)').match('bob 123')
+      md["numbers"].must_equal("123")
+    end
+
+    it "allows access by symbol names when there are named groups" do
+      md = RE2::Regexp.new('(?P<numbers>\d+)').match('bob 123')
+      md[:numbers].must_equal("123")
+    end
+
+    it "allows access by names and indices with mixed groups" do
+      md = RE2::Regexp.new('(?P<name>\w+)(\s*)(?P<numbers>\d+)').match("bob 123")
+      md["name"].must_equal("bob")
+      md[:name].must_equal("bob")
+      md[2].must_equal(" ")
+      md["numbers"].must_equal("123")
+      md[:numbers].must_equal("123")
+    end
+
+    it "returns nil if no such named group exists" do
+      md = RE2::Regexp.new('(\d+)').match("bob 123")
+      md["missing"].must_be_nil
+      md[:missing].must_be_nil
+    end
+  end
+
+  describe "#string" do
+    it "returns the original string to match against" do
+      re = RE2::Regexp.new('(\D+)').match("bob")
+      re.string.must_equal("bob")
+    end
+
+    it "returns a copy, not the actual original" do
+      string = "bob"
+      re = RE2::Regexp.new('(\D+)').match(string)
+      re.string.wont_be_same_as(string)
+    end
+
+    it "returns a frozen string" do
+      re = RE2::Regexp.new('(\D+)').match("bob")
+      re.string.must_be(:frozen?)
+    end
+  end
+
+  describe "#size" do
+    it "returns the number of capturing groups plus the matching string" do
+      md = RE2::Regexp.new('(\d+) (\d+)').match("1234 56")
+      md.size.must_equal(3)
+    end
+  end
+
+  describe "#length" do
+    it "returns the number of capturing groups plus the matching string" do
+      md = RE2::Regexp.new('(\d+) (\d+)').match("1234 56")
+      md.length.must_equal(3)
+    end
+  end
+
+  describe "#regexp" do
+    it "returns the original RE2::Regexp used" do
+      re = RE2::Regexp.new('(\d+)')
+      md = re.match("123")
+      md.regexp.must_be_same_as(re)
+    end
+  end
+
+  describe "#inspect" do
+    it "returns a text representation of the object and indices" do
+      md = RE2::Regexp.new('(\d+) (\d+)').match("1234 56")
+      md.inspect.must_equal('#<RE2::MatchData "1234 56" 1:"1234" 2:"56">')
+    end
+
+    it "represents missing matches as nil" do
+      md = RE2::Regexp.new('(\d+) (\d+)?').match("1234 ")
+      md.inspect.must_equal('#<RE2::MatchData "1234 " 1:"1234" 2:nil>')
+    end
+  end
+
+  describe "#to_s" do
+    it "returns the matching part of the original string" do
+      md = RE2::Regexp.new('(\d{2,5})').match("one two 23456")
+      md.to_s.must_equal("23456")
+    end
+  end
+
+  describe "#to_ary" do
+    it "allows the object to be expanded with an asterisk" do
+      md = RE2::Regexp.new('(\d+) (\d+)').match("1234 56")
+      m1, m2, m3 = *md
+      m1.must_equal("1234 56")
+      m2.must_equal("1234")
+      m3.must_equal("56")
+    end
+  end
+end

data/spec/re2/regexp_spec.rb

@@ -0,0 +1,394 @@
+require "spec_helper"
+
+describe RE2::Regexp do
+  describe "#initialize" do
+    it "returns an instance given only a pattern" do
+      re = RE2::Regexp.new('woo')
+      re.must_be_instance_of(RE2::Regexp)
+    end
+
+    it "returns an instance given a pattern and options" do
+      re = RE2::Regexp.new('woo', :case_sensitive => false)
+      re.must_be_instance_of(RE2::Regexp)
+    end
+  end
+
+  describe "#compile" do
+    it "returns an instance given only a pattern" do
+      re = RE2::Regexp.compile('woo')
+      re.must_be_instance_of(RE2::Regexp)
+    end
+
+    it "returns an instance given a pattern and options" do
+      re = RE2::Regexp.compile('woo', :case_sensitive => false)
+      re.must_be_instance_of(RE2::Regexp)
+    end
+  end
+
+  describe "#options" do
+    it "returns a hash of options" do
+      options = RE2::Regexp.new('woo').options
+      options.must_be_instance_of(Hash)
+    end
+
+    it "is populated with default options when nothing has been set" do
+      options = RE2::Regexp.new('woo').options
+      assert options[:utf8]
+      refute options[:posix_syntax]
+      refute options[:longest_match]
+      assert [:log_errors]
+      refute options[:literal]
+      refute options[:never_nl]
+      assert options[:case_sensitive]
+      refute options[:perl_classes]
+      refute options[:word_boundary]
+      refute options[:one_line]
+    end
+
+    it "is populated with overridden options when specified" do
+      options = RE2::Regexp.new('woo', :case_sensitive => false).options
+      refute options[:case_sensitive]
+    end
+  end
+
+  describe "#error" do
+    it "returns nil if there is no error" do
+      error = RE2::Regexp.new('woo').error
+      error.must_be_nil
+    end
+
+    # Use log_errors => false to suppress RE2's logging to STDERR.
+    it "contains the error string if there is an error" do
+      error = RE2::Regexp.new('wo(o', :log_errors => false).error
+      error.must_equal("missing ): wo(o")
+    end
+  end
+
+  describe "#error_arg" do
+    it "returns nil if there is no error" do
+      error_arg = RE2::Regexp.new('woo').error_arg
+      error_arg.must_be_nil
+    end
+
+    it "returns the offending portin of the regexp if there is an error" do
+      error_arg = RE2::Regexp.new('wo(o', :log_errors => false).error_arg
+      error_arg.must_equal("wo(o")
+    end
+  end
+
+  describe "#program_size" do
+    it "returns a numeric value" do
+      program_size = RE2::Regexp.new('w(o)(o)').program_size
+      program_size.must_be_instance_of(Fixnum)
+    end
+  end
+
+  describe "#to_str" do
+    it "returns the original pattern" do
+      string = RE2::Regexp.new('w(o)(o)').to_str
+      string.must_equal("w(o)(o)")
+    end
+  end
+
+  describe "#pattern" do
+    it "returns the original pattern" do
+      pattern = RE2::Regexp.new('w(o)(o)').pattern
+      pattern.must_equal("w(o)(o)")
+    end
+  end
+
+  describe "#inspect" do
+    it "shows the class name and original pattern" do
+      string = RE2::Regexp.new('w(o)(o)').inspect
+      string.must_equal("#<RE2::Regexp /w(o)(o)/>")
+    end
+  end
+
+  describe "#utf8?" do
+    it "returns true by default" do
+      RE2::Regexp.new('woo').must_be(:utf8?)
+    end
+
+    it "can be overridden on initialization" do
+      re = RE2::Regexp.new('woo', :utf8 => false)
+      re.wont_be(:utf8?)
+    end
+  end
+
+  describe "#posix_syntax?" do
+    it "returns false by default" do
+      RE2::Regexp.new('woo').wont_be(:posix_syntax?)
+    end
+
+    it "can be overridden on initialization" do
+      re = RE2::Regexp.new('woo', :posix_syntax => true)
+      re.must_be(:posix_syntax?)
+    end
+  end
+
+  describe "#literal?" do
+    it "returns false by default" do
+      RE2::Regexp.new('woo').wont_be(:literal?)
+    end
+
+    it "can be overridden on initialization" do
+      re = RE2::Regexp.new('woo', :literal => true)
+      re.must_be(:literal?)
+    end
+  end
+
+  describe "#never_nl?" do
+    it "returns false by default" do
+      RE2::Regexp.new('woo').wont_be(:never_nl?)
+    end
+
+    it "can be overridden on initialization" do
+      re = RE2::Regexp.new('woo', :never_nl => true)
+      re.must_be(:never_nl?)
+    end
+  end
+
+  describe "#case_sensitive?" do
+    it "returns true by default" do
+      RE2::Regexp.new('woo').must_be(:case_sensitive?)
+    end
+
+    it "can be overridden on initialization" do
+      re = RE2::Regexp.new('woo', :case_sensitive => false)
+      re.wont_be(:case_sensitive?)
+    end
+  end
+
+  describe "#case_insensitive?" do
+    it "returns false by default" do
+      RE2::Regexp.new('woo').wont_be(:case_insensitive?)
+    end
+
+    it "can be overridden on initialization" do
+      re = RE2::Regexp.new('woo', :case_sensitive => false)
+      re.must_be(:case_insensitive?)
+    end
+  end
+
+  describe "#casefold?" do
+    it "returns true by default" do
+      RE2::Regexp.new('woo').wont_be(:casefold?)
+    end
+
+    it "can be overridden on initialization" do
+      re = RE2::Regexp.new('woo', :case_sensitive => false)
+      re.must_be(:casefold?)
+    end
+  end
+
+  describe "#longest_match?" do
+    it "returns false by default" do
+      RE2::Regexp.new('woo').wont_be(:casefold?)
+    end
+
+    it "can be overridden on initialization" do
+      re = RE2::Regexp.new('woo', :longest_match => true)
+      re.must_be(:longest_match?)
+    end
+  end
+
+  describe "#log_errors?" do
+    it "returns true by default" do
+      RE2::Regexp.new('woo').must_be(:log_errors?)
+    end
+
+    it "can be overridden on initialization" do
+      re = RE2::Regexp.new('woo', :log_errors => false)
+      re.wont_be(:log_errors?)
+    end
+  end
+
+  describe "#perl_classes?" do
+    it "returns false by default" do
+      RE2::Regexp.new('woo').wont_be(:perl_classes?)
+    end
+
+    it "can be overridden on initialization" do
+      re = RE2::Regexp.new('woo', :perl_classes => true)
+      re.must_be(:perl_classes?)
+    end
+  end
+
+  describe "#word_boundary?" do
+    it "returns false by default" do
+      RE2::Regexp.new('woo').wont_be(:word_boundary?)
+    end
+
+    it "can be overridden on initialization" do
+      re = RE2::Regexp.new('woo', :word_boundary => true)
+      re.must_be(:word_boundary?)
+    end
+  end
+
+  describe "#one_line?" do
+    it "returns false by default" do
+      RE2::Regexp.new('woo').wont_be(:one_line?)
+    end
+
+    it "can be overridden on initialization" do
+      re = RE2::Regexp.new('woo', :one_line => true)
+      re.must_be(:one_line?)
+    end
+  end
+
+  describe "#max_mem" do
+    it "returns the default max memory" do
+      RE2::Regexp.new('woo').max_mem.must_equal(8388608)
+    end
+
+    it "can be overridden on initialization" do
+      re = RE2::Regexp.new('woo', :max_mem => 1024)
+      re.max_mem.must_equal(1024)
+    end
+  end
+
+  describe "#match" do
+    let(:re) { RE2::Regexp.new('My name is (\S+) (\S+)') }
+
+    it "returns match data given only text" do
+      md = re.match("My name is Robert Paulson")
+      md.must_be_instance_of(RE2::MatchData)
+    end
+
+    it "returns nil if there is no match for the given text" do
+      re.match("My age is 99").must_be_nil
+    end
+
+    it "returns only true or false if no matches are requested" do
+      re.match("My name is Robert Paulson", 0).must_equal(true)
+      re.match("My age is 99", 0).must_equal(false)
+    end
+
+    describe "with a specific number of matches under the total in the pattern" do
+      subject { re.match("My name is Robert Paulson", 1) }
+
+      it "returns a match data object" do
+        subject.must_be_instance_of(RE2::MatchData)
+      end
+
+      it "has the whole match and only the specified number of matches" do
+        subject.size.must_equal(2)
+      end
+
+      it "populates any specified matches" do
+        subject[1].must_equal("Robert")
+      end
+
+      it "does not populate any matches that weren't included" do
+        subject[2].must_be_nil
+      end
+    end
+
+    describe "with a number of matches over the total in the pattern" do
+      subject { re.match("My name is Robert Paulson", 5) }
+
+      it "returns a match data object" do
+        subject.must_be_instance_of(RE2::MatchData)
+      end
+
+      it "has the whole match the specified number of matches" do
+        subject.size.must_equal(6)
+      end
+
+      it "populates any specified matches" do
+        subject[1].must_equal("Robert")
+        subject[2].must_equal("Paulson")
+      end
+
+      it "pads the remaining matches with nil" do
+        subject[3].must_be_nil
+        subject[4].must_be_nil
+        subject[5].must_be_nil
+        subject[6].must_be_nil
+      end
+    end
+  end
+
+  describe "#match?" do
+    it "returns only true or false if no matches are requested" do
+      re = RE2::Regexp.new('My name is (\S+) (\S+)')
+      re.match?("My name is Robert Paulson").must_equal(true)
+      re.match?("My age is 99").must_equal(false)
+    end
+  end
+
+  describe "#=~" do
+    it "returns only true or false if no matches are requested" do
+      re = RE2::Regexp.new('My name is (\S+) (\S+)')
+      (re =~ "My name is Robert Paulson").must_equal(true)
+      (re =~ "My age is 99").must_equal(false)
+    end
+  end
+
+  describe "#!~" do
+    it "returns only true or false if no matches are requested" do
+      re = RE2::Regexp.new('My name is (\S+) (\S+)')
+      (re !~ "My name is Robert Paulson").must_equal(false)
+      (re !~ "My age is 99").must_equal(true)
+    end
+  end
+
+  describe "#===" do
+    it "returns only true or false if no matches are requested" do
+      re = RE2::Regexp.new('My name is (\S+) (\S+)')
+      (re === "My name is Robert Paulson").must_equal(true)
+      (re === "My age is 99").must_equal(false)
+    end
+  end
+
+  describe "#ok?" do
+    it "returns true for valid regexps" do
+      RE2::Regexp.new('woo').must_be(:ok?)
+      RE2::Regexp.new('wo(o)').must_be(:ok?)
+      RE2::Regexp.new('((\d)\w+){3,}').must_be(:ok?)
+    end
+
+    it "returns false for invalid regexps" do
+      RE2::Regexp.new('wo(o', :log_errors => false).wont_be(:ok?)
+      RE2::Regexp.new('wo[o', :log_errors => false).wont_be(:ok?)
+      RE2::Regexp.new('*', :log_errors => false).wont_be(:ok?)
+    end
+  end
+
+  describe "#escape" do
+    it "transforms a string into a regexp" do
+      RE2::Regexp.escape("1.5-2.0?").must_equal('1\.5\-2\.0\?')
+    end
+  end
+
+  describe "#quote" do
+    it "transforms a string into a regexp" do
+      RE2::Regexp.quote("1.5-2.0?").must_equal('1\.5\-2\.0\?')
+    end
+  end
+
+  describe "#number_of_capturing_groups" do
+    it "returns the number of groups in a regexp" do
+      RE2::Regexp.new('(a)(b)(c)').number_of_capturing_groups.must_equal(3)
+      RE2::Regexp.new('abc').number_of_capturing_groups.must_equal(0)
+      RE2::Regexp.new('a((b)c)').number_of_capturing_groups.must_equal(2)
+    end
+  end
+
+  describe "#named_capturing_groups" do
+    it "returns a hash of names to indices" do
+      RE2::Regexp.new('(?P<bob>a)').named_capturing_groups.must_be_instance_of(Hash)
+    end
+
+    it "maps names to indices with only one group" do
+      groups = RE2::Regexp.new('(?P<bob>a)').named_capturing_groups
+      groups["bob"].must_equal(1)
+    end
+
+    it "maps names to indices with several groups" do
+      groups = RE2::Regexp.new('(?P<bob>a)(o)(?P<rob>e)').named_capturing_groups
+      groups["bob"].must_equal(1)
+      groups["rob"].must_equal(3)
+    end
+  end
+end