re2 1.4.0 → 1.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ce0e303b87738a767776165216cbbd8cf0f63ec9dba3ef4389f657cbb5da8dc3
-  data.tar.gz: 61983a9e93dc64334d43a41f3f978ff71de020bd9d6f27bc409431a313ea58e0
+  metadata.gz: 2151621115d04b197403c0f67276347c205928136405c05aac1fc70bf3a00dec
+  data.tar.gz: 8ba805a95c535ab7d30296a830448dea51da4f5f699a6aa3f858296b2590d188
 SHA512:
-  metadata.gz: 229f667e12094ae2d42ae3d72a08aa0567cf17e1d666d9677b6b0bdfccc549f241870085ac918789fbbcd0fcb538a942a31f6922f32d88cc7b54043b553f35e3
-  data.tar.gz: 850d6dc79bcfbfe96a913ac93ddc2c8d4e1b79ddd8aa50eb951bfaae99e3a1688ff31fd2e55c2e497946b9ea4913bcca4938070b6fa37f2ca77d88721652ca66
+  metadata.gz: 010e20dae629df302c35c6d5cc412c5a0add1cc3f0b6357114ce64c5d77e6c3bbca7401e57c0b86be5fe87acae17162cd7c860c079dc2c57898761f9fd8d4ce4
+  data.tar.gz: 6bfa2db432e91b87ab5d6fa21babd07a675df3b22904e20f1491322b1d34c8fe1c5814783049c33f84ab8f22e0b3c2ef9c2308161f8694dd6bcbd8ec4da278a4

data/README.md

@@ -4,8 +4,8 @@ re2 [![Build Status](https://github.com/mudge/re2/actions/workflows/tests.yml/ba
 A Ruby binding to [re2][], an "efficient, principled regular expression
 library".
 
-**Current version:** 1.4.0  
-**Supported Ruby versions:** 1.8.7, 1.9.3, 2.0, 2.1, 2.2, 2.3, 2.4, 2.5, 2.6, 2.7, 3.0  
+**Current version:** 1.6.0  
+**Supported Ruby versions:** 1.8.7, 1.9.3, 2.0, 2.1, 2.2, 2.3, 2.4, 2.5, 2.6, 2.7, 3.0, 3.1  
 **Supported re2 versions:** libre2.0 (< 2020-03-02), libre2.1 (2020-03-02), libre2.6 (2020-03-03), libre2.7 (2020-05-01), libre2.8 (2020-07-06), libre2.9 (2020-11-01)
 
 Installation
@@ -131,6 +131,43 @@ enum.next #=> ["It"]
 enum.next #=> ["is"]
 ```
 
+As of 1.5.0, you can use `RE2::Set` to match multiple patterns against a
+string. Calling `RE2::Set#add` with a pattern will return an integer index of
+the pattern. After all patterns have been added, the set can be compiled using
+`RE2::Set#compile`, and then `RE2::Set#match` will return an `Array<Integer>`
+containing the indices of all the patterns that matched.
+
+```ruby
+set = RE2::Set.new
+set.add("abc") #=> 0
+set.add("def") #=> 1
+set.add("ghi") #=> 2
+set.compile #=> true
+set.match("abcdefghi") #=> [0, 1, 2]
+set.match("ghidefabc") #=> [2, 1, 0]
+```
+
+As of 1.6.0, you can use [Ruby's pattern matching](https://docs.ruby-lang.org/en/3.0/syntax/pattern_matching_rdoc.html) against `RE2::MatchData` with both array patterns and hash patterns:
+
+```ruby
+case RE2('(\w+) (\d+)').match("Alice 42")
+in [name, age]
+  puts "My name is #{name} and I am #{age} years old"
+else
+  puts "No match!"
+end
+# My name is Alice and I am 42 years old
+
+
+case RE2('(?P<name>\w+) (?P<age>\d+)').match("Alice 42")
+in {name:, age:}
+  puts "My name is #{name} and I am #{age} years old"
+else
+  puts "No match!"
+end
+# My name is Alice and I am 42 years old
+```
+
 Features
 --------
 
@@ -149,6 +186,8 @@ Features
 
 * Incrementally scanning text with `re2.scan(text)`
 
+* Search a collection of patterns simultaneously with `RE2::Set`
+
 * Checking regular expression compilation with `re2.ok?`, `re2.error` and
   `re2.error_arg`
 
@@ -167,6 +206,8 @@ Features
   [`RE2.escape(unquoted)`](https://github.com/google/re2/blob/2016-02-01/re2/re2.h#L418) and
   `RE2.quote(unquoted)`
 
+* Pattern matching with `RE2::MatchData`
+
 Contributions
 -------------
 
@@ -177,7 +218,9 @@ Contributions
 * Thanks to [Sebastian Reitenbach](https://github.com/buzzdeee) for reporting
   the deprecation and removal of the `utf8` encoding option in re2;
 * Thanks to [Sergio Medina](https://github.com/serch) for reporting a bug when
-  using `RE2::Scanner#scan` with an invalid regular expression.
+  using `RE2::Scanner#scan` with an invalid regular expression;
+* Thanks to [Pritam Baral](https://github.com/pritambaral) for contributed the
+  initial support for `RE2::Set`.
 
 Contact
 -------

data/ext/re2/extconf.rb

@@ -88,4 +88,28 @@ SRC
   end
 end
 
+checking_for("RE2::Set::Match() with error information") do
+  test_re2_set_match_signature = <<SRC
+#include <vector>
+#include <re2/re2.h>
+#include <re2/set.h>
+
+int main() {
+  RE2::Set s(RE2::DefaultOptions, RE2::UNANCHORED);
+  s.Add("foo", NULL);
+  s.Compile();
+
+  std::vector<int> v;
+  RE2::Set::ErrorInfo ei;
+  s.Match("foo", &v, &ei);
+
+  return 0;
+}
+SRC
+
+  if try_compile(test_re2_set_match_signature, compile_options)
+    $defs.push("-DHAVE_ERROR_INFO_ARGUMENT")
+  end
+end
+
 create_makefile("re2")

data/ext/re2/re2.cc

@@ -8,6 +8,7 @@
 
 #include <ruby.h>
 #include <re2/re2.h>
+#include <re2/set.h>
 #include <stdint.h>
 #include <string>
 #include <sstream>
@@ -93,12 +94,82 @@ typedef struct {
   VALUE regexp, text;
 } re2_scanner;
 
-VALUE re2_mRE2, re2_cRegexp, re2_cMatchData, re2_cScanner;
+typedef struct {
+  RE2::Set *set;
+} re2_set;
+
+VALUE re2_mRE2, re2_cRegexp, re2_cMatchData, re2_cScanner, re2_cSet,
+      re2_eSetMatchError, re2_eSetUnsupportedError;
 
 /* Symbols used in RE2 options. */
 static ID id_utf8, id_posix_syntax, id_longest_match, id_log_errors,
           id_max_mem, id_literal, id_never_nl, id_case_sensitive,
-          id_perl_classes, id_word_boundary, id_one_line;
+          id_perl_classes, id_word_boundary, id_one_line,
+          id_unanchored, id_anchor_start, id_anchor_both, id_exception;
+
+void parse_re2_options(RE2::Options& re2_options, VALUE options) {
+  if (TYPE(options) != T_HASH) {
+    rb_raise(rb_eArgError, "options should be a hash");
+  }
+  VALUE utf8, posix_syntax, longest_match, log_errors,
+        max_mem, literal, never_nl, case_sensitive, perl_classes,
+        word_boundary, one_line;
+
+  utf8 = rb_hash_aref(options, ID2SYM(id_utf8));
+  if (!NIL_P(utf8)) {
+    re2_options.set_encoding(RTEST(utf8) ? RE2::Options::EncodingUTF8 : RE2::Options::EncodingLatin1);
+  }
+
+  posix_syntax = rb_hash_aref(options, ID2SYM(id_posix_syntax));
+  if (!NIL_P(posix_syntax)) {
+    re2_options.set_posix_syntax(RTEST(posix_syntax));
+  }
+
+  longest_match = rb_hash_aref(options, ID2SYM(id_longest_match));
+  if (!NIL_P(longest_match)) {
+    re2_options.set_longest_match(RTEST(longest_match));
+  }
+
+  log_errors = rb_hash_aref(options, ID2SYM(id_log_errors));
+  if (!NIL_P(log_errors)) {
+    re2_options.set_log_errors(RTEST(log_errors));
+  }
+
+  max_mem = rb_hash_aref(options, ID2SYM(id_max_mem));
+  if (!NIL_P(max_mem)) {
+    re2_options.set_max_mem(NUM2INT(max_mem));
+  }
+
+  literal = rb_hash_aref(options, ID2SYM(id_literal));
+  if (!NIL_P(literal)) {
+    re2_options.set_literal(RTEST(literal));
+  }
+
+  never_nl = rb_hash_aref(options, ID2SYM(id_never_nl));
+  if (!NIL_P(never_nl)) {
+    re2_options.set_never_nl(RTEST(never_nl));
+  }
+
+  case_sensitive = rb_hash_aref(options, ID2SYM(id_case_sensitive));
+  if (!NIL_P(case_sensitive)) {
+    re2_options.set_case_sensitive(RTEST(case_sensitive));
+  }
+
+  perl_classes = rb_hash_aref(options, ID2SYM(id_perl_classes));
+  if (!NIL_P(perl_classes)) {
+    re2_options.set_perl_classes(RTEST(perl_classes));
+  }
+
+  word_boundary = rb_hash_aref(options, ID2SYM(id_word_boundary));
+  if (!NIL_P(word_boundary)) {
+    re2_options.set_word_boundary(RTEST(word_boundary));
+  }
+
+  one_line = rb_hash_aref(options, ID2SYM(id_one_line));
+  if (!NIL_P(one_line)) {
+    re2_options.set_one_line(RTEST(one_line));
+  }
+}
 
 void re2_matchdata_mark(re2_matchdata* self) {
   rb_gc_mark(self->regexp);
@@ -616,6 +687,112 @@ static VALUE re2_matchdata_inspect(VALUE self) {
   return result;
 }
 
+/*
+ * Returns the array of submatches for pattern matching.
+ *
+ * @return [Array<String, nil>] the array of submatches
+ * @example
+ *   m = RE2::Regexp.new('(\d+)').match("bob 123")
+ *   m.deconstruct    #=> ["123"]
+ *
+ * @example pattern matching
+ *   case RE2::Regexp.new('(\d+) (\d+)').match("bob 123 456")
+ *   in x, y
+ *     puts "Matched #{x} #{y}"
+ *   else
+ *     puts "Unrecognised match"
+ *   end
+ */
+static VALUE re2_matchdata_deconstruct(VALUE self) {
+  int i;
+  re2_matchdata *m;
+  re2_pattern *p;
+  re2::StringPiece *match;
+  VALUE array;
+
+  Data_Get_Struct(self, re2_matchdata, m);
+  Data_Get_Struct(m->regexp, re2_pattern, p);
+
+  array = rb_ary_new2(m->number_of_matches - 1);
+  for (i = 1; i < m->number_of_matches; i++) {
+    match = &m->matches[i];
+
+    if (match->empty()) {
+      rb_ary_push(array, Qnil);
+    } else {
+      rb_ary_push(array, ENCODED_STR_NEW(match->data(), match->size(),
+            p->pattern->options().encoding() == RE2::Options::EncodingUTF8 ? "UTF-8" : "ISO-8859-1"));
+    }
+  }
+
+  return array;
+}
+
+/*
+ * Returns a hash of capturing group names to submatches for pattern matching.
+ *
+ * As this is used by Ruby's pattern matching, it will return an empty hash if given
+ * more keys than there are capturing groups. Given keys will populate the hash in
+ * order but an invalid name will cause the hash to be immediately returned.
+ *
+ * @return [Hash] a hash of capturing group names to submatches
+ * @param [Array<Symbol>, nil] keys an array of Symbol capturing group names or nil to return all names
+ * @example
+ *   m = RE2::Regexp.new('(?P<numbers>\d+) (?P<letters>[a-zA-Z]+)').match('123 abc')
+ *   m.deconstruct_keys(nil)                  #=> {:numbers => "123", :letters => "abc"}
+ *   m.deconstruct_keys([:numbers])           #=> {:numbers => "123"}
+ *   m.deconstruct_keys([:fruit])             #=> {}
+ *   m.deconstruct_keys([:letters, :fruit])   #=> {:letters => "abc"}
+ *
+ * @example pattern matching
+ *   case RE2::Regexp.new('(?P<numbers>\d+) (?P<letters>[a-zA-Z]+)').match('123 abc')
+ *   in numbers:, letters:
+ *     puts "Numbers: #{numbers}, letters: #{letters}"
+ *   else
+ *     puts "Unrecognised match"
+ *   end
+ */
+static VALUE re2_matchdata_deconstruct_keys(VALUE self, VALUE keys) {
+  int i;
+  VALUE capturing_groups, key;
+  re2_matchdata *m;
+  re2_pattern *p;
+  map<string, int> groups;
+  map<string, int>::iterator iterator;
+
+  Data_Get_Struct(self, re2_matchdata, m);
+  Data_Get_Struct(m->regexp, re2_pattern, p);
+
+  groups = p->pattern->NamedCapturingGroups();
+  capturing_groups = rb_hash_new();
+
+  if (NIL_P(keys)) {
+    for (iterator = groups.begin(); iterator != groups.end(); iterator++) {
+      rb_hash_aset(capturing_groups,
+          ID2SYM(rb_intern(iterator->first.data())),
+          re2_matchdata_nth_match(iterator->second, self));
+    }
+  } else {
+    Check_Type(keys, T_ARRAY);
+
+    if (p->pattern->NumberOfCapturingGroups() >= RARRAY_LEN(keys)) {
+      for (i = 0; i < RARRAY_LEN(keys); i++) {
+        key = rb_ary_entry(keys, i);
+        Check_Type(key, T_SYMBOL);
+        string name(rb_id2name(SYM2ID(key)));
+
+        if (groups.count(name) == 0) {
+          break;
+        }
+
+        rb_hash_aset(capturing_groups, key, re2_matchdata_nth_match(groups[name], self));
+      }
+    }
+  }
+
+  return capturing_groups;
+}
+
 /*
  * Returns a new RE2 object with a compiled version of
  * +pattern+ stored inside. Equivalent to +RE2.new+.
@@ -667,75 +844,15 @@ static VALUE re2_re2(int argc, VALUE *argv, VALUE self) {
  *   @raise [NoMemoryError] if memory could not be allocated for the compiled pattern
  */
 static VALUE re2_regexp_initialize(int argc, VALUE *argv, VALUE self) {
-  VALUE pattern, options, utf8, posix_syntax, longest_match, log_errors,
-        max_mem, literal, never_nl, case_sensitive, perl_classes,
-        word_boundary, one_line;
+  VALUE pattern, options;
   re2_pattern *p;
 
   rb_scan_args(argc, argv, "11", &pattern, &options);
   Data_Get_Struct(self, re2_pattern, p);
 
   if (RTEST(options)) {
-    if (TYPE(options) != T_HASH) {
-      rb_raise(rb_eArgError, "options should be a hash");
-    }
-
     RE2::Options re2_options;
-
-    utf8 = rb_hash_aref(options, ID2SYM(id_utf8));
-    if (!NIL_P(utf8)) {
-      re2_options.set_encoding(RTEST(utf8) ? RE2::Options::EncodingUTF8 : RE2::Options::EncodingLatin1);
-    }
-
-    posix_syntax = rb_hash_aref(options, ID2SYM(id_posix_syntax));
-    if (!NIL_P(posix_syntax)) {
-      re2_options.set_posix_syntax(RTEST(posix_syntax));
-    }
-
-    longest_match = rb_hash_aref(options, ID2SYM(id_longest_match));
-    if (!NIL_P(longest_match)) {
-      re2_options.set_longest_match(RTEST(longest_match));
-    }
-
-    log_errors = rb_hash_aref(options, ID2SYM(id_log_errors));
-    if (!NIL_P(log_errors)) {
-      re2_options.set_log_errors(RTEST(log_errors));
-    }
-
-    max_mem = rb_hash_aref(options, ID2SYM(id_max_mem));
-    if (!NIL_P(max_mem)) {
-      re2_options.set_max_mem(NUM2INT(max_mem));
-    }
-
-    literal = rb_hash_aref(options, ID2SYM(id_literal));
-    if (!NIL_P(literal)) {
-      re2_options.set_literal(RTEST(literal));
-    }
-
-    never_nl = rb_hash_aref(options, ID2SYM(id_never_nl));
-    if (!NIL_P(never_nl)) {
-      re2_options.set_never_nl(RTEST(never_nl));
-    }
-
-    case_sensitive = rb_hash_aref(options, ID2SYM(id_case_sensitive));
-    if (!NIL_P(case_sensitive)) {
-      re2_options.set_case_sensitive(RTEST(case_sensitive));
-    }
-
-    perl_classes = rb_hash_aref(options, ID2SYM(id_perl_classes));
-    if (!NIL_P(perl_classes)) {
-      re2_options.set_perl_classes(RTEST(perl_classes));
-    }
-
-    word_boundary = rb_hash_aref(options, ID2SYM(id_word_boundary));
-    if (!NIL_P(word_boundary)) {
-      re2_options.set_word_boundary(RTEST(word_boundary));
-    }
-
-    one_line = rb_hash_aref(options, ID2SYM(id_one_line));
-    if (!NIL_P(one_line)) {
-      re2_options.set_one_line(RTEST(one_line));
-    }
+    parse_re2_options(re2_options, options);
 
     p->pattern = new(nothrow) RE2(StringValuePtr(pattern), re2_options);
   } else {
@@ -1234,7 +1351,7 @@ static VALUE re2_regexp_match(int argc, VALUE *argv, VALUE self) {
  *
  * @return [Boolean] whether the match was successful
  */
-static VALUE re2_regexp_match_query(VALUE self, VALUE text) {
+static VALUE re2_regexp_match_p(VALUE self, VALUE text) {
   VALUE argv[2];
   argv[0] = text;
   argv[1] = INT2FIX(0);
@@ -1362,6 +1479,257 @@ static VALUE re2_QuoteMeta(VALUE self, VALUE unquoted) {
   return rb_str_new(quoted_string.data(), quoted_string.size());
 }
 
+void re2_set_free(re2_set *self) {
+  if (self->set) {
+    delete self->set;
+  }
+  free(self);
+}
+
+static VALUE re2_set_allocate(VALUE klass) {
+  re2_set *s;
+  VALUE result = Data_Make_Struct(klass, re2_set, 0, re2_set_free, s);
+  return result;
+}
+
+/*
+ * Returns a new {RE2::Set} object, a collection of patterns that can be
+ * searched for simultaneously.
+ *
+ * @return [RE2::Set]
+ *
+ * @overload initialize
+ *   Returns a new {RE2::Set} object for unanchored patterns with the default
+ *   options.
+ *
+ *   @raise [NoMemoryError] if memory could not be allocated for the compiled pattern
+ *   @return [RE2::Set]
+ *
+ * @overload initialize(anchor)
+ *   Returns a new {RE2::Set} object for the specified anchor with the default
+ *   options.
+ *
+ *   @param [Symbol] anchor One of :unanchored, :anchor_start, :anchor_both
+ *   @raise [ArgumentError] if anchor is not :unanchored, :anchor_start or :anchor_both
+ *   @raise [NoMemoryError] if memory could not be allocated for the compiled pattern
+ *
+ * @overload initialize(anchor, options)
+ *   Returns a new {RE2::Set} object with the specified options.
+ *
+ *   @param [Symbol] anchor One of :unanchored, :anchor_start, :anchor_both
+ *   @param [Hash] options the options with which to compile the pattern
+ *   @option options [Boolean] :utf8 (true) text and pattern are UTF-8; otherwise Latin-1
+ *   @option options [Boolean] :posix_syntax (false) restrict regexps to POSIX egrep syntax
+ *   @option options [Boolean] :longest_match (false) search for longest match, not first match
+ *   @option options [Boolean] :log_errors (true) log syntax and execution errors to ERROR
+ *   @option options [Fixnum] :max_mem approx. max memory footprint of RE2
+ *   @option options [Boolean] :literal (false) interpret string as literal, not regexp
+ *   @option options [Boolean] :never_nl (false) never match \n, even if it is in regexp
+ *   @option options [Boolean] :case_sensitive (true) match is case-sensitive (regexp can override with (?i) unless in posix_syntax mode)
+ *   @option options [Boolean] :perl_classes (false) allow Perl's \d \s \w \D \S \W when in posix_syntax mode
+ *   @option options [Boolean] :word_boundary (false) allow \b \B (word boundary and not) when in posix_syntax mode
+ *   @option options [Boolean] :one_line (false) ^ and $ only match beginning and end of text when in posix_syntax mode
+ *   @return [RE2::Set] an RE2::Set with the specified anchor and options
+ *   @raise [ArgumentError] if anchor is not one of the accepted choices
+ *   @raise [NoMemoryError] if memory could not be allocated for the compiled pattern
+ */
+static VALUE re2_set_initialize(int argc, VALUE *argv, VALUE self) {
+  VALUE anchor, options;
+  re2_set *s;
+  RE2::Anchor re2_anchor;
+  RE2::Options re2_options;
+
+  rb_scan_args(argc, argv, "02", &anchor, &options);
+  Data_Get_Struct(self, re2_set, s);
+
+  if (RTEST(options)) {
+    parse_re2_options(re2_options, options);
+  }
+  if (NIL_P(anchor)) {
+    re2_anchor = RE2::UNANCHORED;
+  } else {
+    Check_Type(anchor, T_SYMBOL);
+    ID id_anchor = SYM2ID(anchor);
+    if (id_anchor == id_unanchored) {
+      re2_anchor = RE2::UNANCHORED;
+    } else if (id_anchor == id_anchor_start) {
+      re2_anchor = RE2::ANCHOR_START;
+    } else if (id_anchor == id_anchor_both) {
+      re2_anchor = RE2::ANCHOR_BOTH;
+    } else {
+      rb_raise(rb_eArgError, "anchor should be one of: :unanchored, :anchor_start, :anchor_both");
+    }
+  }
+
+  s->set = new(nothrow) RE2::Set(re2_options, re2_anchor);
+  if (s->set == 0) {
+    rb_raise(rb_eNoMemError, "not enough memory to allocate RE2::Set object");
+  }
+
+  return self;
+}
+
+/*
+ * Adds a pattern to the set. Returns the index that will identify the pattern
+ * in the output of #match. Cannot be called after #compile has been called.
+ *
+ * @param [String] pattern the regex pattern
+ * @return [Integer] the index of the pattern in the set
+ * @raise [ArgumentError] if called after compile or the pattern is rejected
+ * @example
+ *   set = RE2::Set.new
+ *   set.add("abc")    #=> 0
+ *   set.add("def")    #=> 1
+ */
+static VALUE re2_set_add(VALUE self, VALUE pattern) {
+  Check_Type(pattern, T_STRING);
+  re2::StringPiece regex(RSTRING_PTR(pattern), RSTRING_LEN(pattern));
+  std::string err;
+  re2_set *s;
+  Data_Get_Struct(self, re2_set, s);
+  int index = s->set->Add(regex, &err);
+  if (index < 0) {
+    rb_raise(rb_eArgError, "str rejected by RE2::Set->Add(): %s", err.c_str());
+  }
+
+  return INT2FIX(index);
+}
+
+/*
+ * Compiles a Set so it can be used to match against. Must be called after #add
+ * and before #match.
+ *
+ * @return [Bool] whether compilation was a success
+ * @example
+ *   set = RE2::Set.new
+ *   set.add("abc")
+ *   set.compile    # => true
+ */
+static VALUE re2_set_compile(VALUE self) {
+  re2_set *s;
+  Data_Get_Struct(self, re2_set, s);
+
+  return BOOL2RUBY(s->set->Compile());
+}
+
+/*
+ * Returns whether the underlying re2 version outputs error information from
+ * RE2::Set::Match. If not, #match will raise an error if attempting to set its
+ * :exception option to true.
+ *
+ * @return [Bool] whether the underlying re2 outputs error information from Set matches
+ */
+static VALUE re2_set_match_raises_errors_p(VALUE self) {
+  UNUSED(self);
+#ifdef HAVE_ERROR_INFO_ARGUMENT
+  return Qtrue;
+#else
+  return Qfalse;
+#endif
+}
+
+/*
+ * Matches the given text against patterns in the set, returning an array of
+ * integer indices of the matching patterns if matched or an empty array if
+ * there are no matches.
+ *
+ * @return [Array<Integer>]
+ *
+ * @overload match(str)
+ *   Returns an array of integer indices of patterns matching the given string
+ *   (if any). Raises exceptions if there are any errors while matching.
+ *
+ *   @param [String] str the text to match against
+ *   @return [Array<Integer>] the indices of matching regexps
+ *   @raise [MatchError] if an error occurs while matching
+ *   @raise [UnsupportedError] if the underlying version of re2 does not output error information
+ *   @example
+ *     set = RE2::Set.new
+ *     set.add("abc")
+ *     set.add("def")
+ *     set.compile
+ *     set.match("abcdef")    # => [0, 1]
+ *
+ * @overload match(str, options)
+ *   Returns an array of integer indices of patterns matching the given string
+ *   (if any). Raises exceptions if there are any errors while matching and the
+ *   :exception option is set to true.
+ *
+ *   @param [String] str the text to match against
+ *   @param [Hash] options the options with which to match
+ *   @option options [Boolean] :exception (true) whether to raise exceptions with re2's error information (not supported on ABI version 0 of re2)
+ *   @return [Array<Integer>] the indices of matching regexps
+ *   @raise [MatchError] if an error occurs while matching
+ *   @raise [UnsupportedError] if the underlying version of re2 does not output error information
+ *   @example
+ *     set = RE2::Set.new
+ *     set.add("abc")
+ *     set.add("def")
+ *     set.compile
+ *     set.match("abcdef", :exception => true)    # => [0, 1]
+ */
+static VALUE re2_set_match(int argc, VALUE *argv, VALUE self) {
+  VALUE str, options, exception_option;
+  bool raise_exception = true;
+  rb_scan_args(argc, argv, "11", &str, &options);
+  Check_Type(str, T_STRING);
+  re2::StringPiece data(RSTRING_PTR(str), RSTRING_LEN(str));
+  std::vector<int> v;
+  re2_set *s;
+  Data_Get_Struct(self, re2_set, s);
+
+  if (RTEST(options)) {
+    Check_Type(options, T_HASH);
+
+    exception_option = rb_hash_aref(options, ID2SYM(id_exception));
+    if (!NIL_P(exception_option)) {
+      raise_exception = RTEST(exception_option);
+    }
+  }
+
+  if (raise_exception) {
+#ifdef HAVE_ERROR_INFO_ARGUMENT
+    RE2::Set::ErrorInfo e;
+    bool match_failed = !s->set->Match(data, &v, &e);
+    VALUE result = rb_ary_new2(v.size());
+
+    if (match_failed) {
+      switch (e.kind) {
+        case RE2::Set::kNoError:
+          break;
+        case RE2::Set::kNotCompiled:
+          rb_raise(re2_eSetMatchError, "#match must not be called before #compile");
+        case RE2::Set::kOutOfMemory:
+          rb_raise(re2_eSetMatchError, "The DFA ran out of memory");
+        case RE2::Set::kInconsistent:
+          rb_raise(re2_eSetMatchError, "RE2::Prog internal error");
+        default:  // Just in case a future version of libre2 adds new ErrorKinds
+          rb_raise(re2_eSetMatchError, "Unknown RE2::Set::ErrorKind: %d", e.kind);
+      }
+    } else {
+      for (size_t i = 0; i < v.size(); i++) {
+        rb_ary_push(result, INT2FIX(v[i]));
+      }
+    }
+
+    return result;
+#else
+    rb_raise(re2_eSetUnsupportedError, "current version of RE2::Set::Match() does not output error information, :exception option can only be set to false");
+#endif
+  } else {
+    bool matched = s->set->Match(data, &v);
+    VALUE result = rb_ary_new2(v.size());
+
+    if (matched) {
+      for (size_t i = 0; i < v.size(); i++) {
+        rb_ary_push(result, INT2FIX(v[i]));
+      }
+    }
+
+    return result;
+  }
+}
+
 /* Forward declare Init_re2 to be called by C code but define it separately so
  * that YARD can parse it.
  */
@@ -1372,12 +1740,18 @@ void Init_re2(void) {
   re2_cRegexp = rb_define_class_under(re2_mRE2, "Regexp", rb_cObject);
   re2_cMatchData = rb_define_class_under(re2_mRE2, "MatchData", rb_cObject);
   re2_cScanner = rb_define_class_under(re2_mRE2, "Scanner", rb_cObject);
+  re2_cSet = rb_define_class_under(re2_mRE2, "Set", rb_cObject);
+  re2_eSetMatchError = rb_define_class_under(re2_cSet, "MatchError",
+      rb_const_get(rb_cObject, rb_intern("StandardError")));
+  re2_eSetUnsupportedError = rb_define_class_under(re2_cSet, "UnsupportedError",
+      rb_const_get(rb_cObject, rb_intern("StandardError")));
 
   rb_define_alloc_func(re2_cRegexp, (VALUE (*)(VALUE))re2_regexp_allocate);
   rb_define_alloc_func(re2_cMatchData,
       (VALUE (*)(VALUE))re2_matchdata_allocate);
   rb_define_alloc_func(re2_cScanner,
       (VALUE (*)(VALUE))re2_scanner_allocate);
+  rb_define_alloc_func(re2_cSet, (VALUE (*)(VALUE))re2_set_allocate);
 
   rb_define_method(re2_cMatchData, "string",
       RUBY_METHOD_FUNC(re2_matchdata_string), 0);
@@ -1394,10 +1768,15 @@ void Init_re2(void) {
   rb_define_method(re2_cMatchData, "end",
       RUBY_METHOD_FUNC(re2_matchdata_end), 1);
   rb_define_method(re2_cMatchData, "[]", RUBY_METHOD_FUNC(re2_matchdata_aref),
-      -1); rb_define_method(re2_cMatchData, "to_s",
+      -1);
+  rb_define_method(re2_cMatchData, "to_s",
         RUBY_METHOD_FUNC(re2_matchdata_to_s), 0);
   rb_define_method(re2_cMatchData, "inspect",
       RUBY_METHOD_FUNC(re2_matchdata_inspect), 0);
+  rb_define_method(re2_cMatchData, "deconstruct",
+      RUBY_METHOD_FUNC(re2_matchdata_deconstruct), 0);
+  rb_define_method(re2_cMatchData, "deconstruct_keys",
+      RUBY_METHOD_FUNC(re2_matchdata_deconstruct_keys), 1);
 
   rb_define_method(re2_cScanner, "string",
       RUBY_METHOD_FUNC(re2_scanner_string), 0);
@@ -1428,11 +1807,11 @@ void Init_re2(void) {
   rb_define_method(re2_cRegexp, "match", RUBY_METHOD_FUNC(re2_regexp_match),
       -1);
   rb_define_method(re2_cRegexp, "match?",
-      RUBY_METHOD_FUNC(re2_regexp_match_query), 1);
+      RUBY_METHOD_FUNC(re2_regexp_match_p), 1);
   rb_define_method(re2_cRegexp, "=~",
-      RUBY_METHOD_FUNC(re2_regexp_match_query), 1);
+      RUBY_METHOD_FUNC(re2_regexp_match_p), 1);
   rb_define_method(re2_cRegexp, "===",
-      RUBY_METHOD_FUNC(re2_regexp_match_query), 1);
+      RUBY_METHOD_FUNC(re2_regexp_match_p), 1);
   rb_define_method(re2_cRegexp, "scan",
       RUBY_METHOD_FUNC(re2_regexp_scan), 1);
   rb_define_method(re2_cRegexp, "to_s", RUBY_METHOD_FUNC(re2_regexp_to_s), 0);
@@ -1471,6 +1850,14 @@ void Init_re2(void) {
   rb_define_method(re2_cRegexp, "one_line?",
       RUBY_METHOD_FUNC(re2_regexp_one_line), 0);
 
+  rb_define_singleton_method(re2_cSet, "match_raises_errors?",
+      RUBY_METHOD_FUNC(re2_set_match_raises_errors_p), 0);
+  rb_define_method(re2_cSet, "initialize",
+      RUBY_METHOD_FUNC(re2_set_initialize), -1);
+  rb_define_method(re2_cSet, "add", RUBY_METHOD_FUNC(re2_set_add), 1);
+  rb_define_method(re2_cSet, "compile", RUBY_METHOD_FUNC(re2_set_compile), 0);
+  rb_define_method(re2_cSet, "match", RUBY_METHOD_FUNC(re2_set_match), -1);
+
   rb_define_module_function(re2_mRE2, "Replace",
       RUBY_METHOD_FUNC(re2_Replace), 3);
   rb_define_module_function(re2_mRE2, "GlobalReplace",
@@ -1498,6 +1885,10 @@ void Init_re2(void) {
   id_perl_classes = rb_intern("perl_classes");
   id_word_boundary = rb_intern("word_boundary");
   id_one_line = rb_intern("one_line");
+  id_unanchored = rb_intern("unanchored");
+  id_anchor_start = rb_intern("anchor_start");
+  id_anchor_both = rb_intern("anchor_both");
+  id_exception = rb_intern("exception");
 
   #if 0
     /* Fake so YARD generates the file. */

data/spec/re2/match_data_spec.rb

@@ -241,4 +241,62 @@ RSpec.describe RE2::MatchData do
       expect(md.end(:foo)).to be_nil
     end
   end
+
+  describe "#deconstruct" do
+    it "returns all capturing groups" do
+      md = RE2::Regexp.new('w(o)(o)').match('woo')
+
+      expect(md.deconstruct).to eq(['o', 'o'])
+    end
+
+    it "includes optional capturing groups as nil" do
+      md = RE2::Regexp.new('w(.)(.)(.)?').match('woo')
+
+      expect(md.deconstruct).to eq(['o', 'o', nil])
+    end
+  end
+
+  describe "#deconstruct_keys" do
+    it "returns all named captures if given nil" do
+      md = RE2::Regexp.new('(?P<numbers>\d+) (?P<letters>[a-zA-Z]+)').match('123 abc')
+
+      expect(md.deconstruct_keys(nil)).to eq(:numbers => '123', :letters => 'abc')
+    end
+
+    it "returns only named captures if given names" do
+      md = RE2::Regexp.new('(?P<numbers>\d+) (?P<letters>[a-zA-Z]+)').match('123 abc')
+
+      expect(md.deconstruct_keys([:numbers])).to eq(:numbers => '123')
+    end
+
+    it "returns named captures up until an invalid name is given" do
+      md = RE2::Regexp.new('(?P<numbers>\d+) (?P<letters>[a-zA-Z]+)').match('123 abc')
+
+      expect(md.deconstruct_keys([:numbers, :punctuation])).to eq(:numbers => '123')
+    end
+
+    it "returns an empty hash if given more capture names than exist" do
+      md = RE2::Regexp.new('(?P<numbers>\d+) (?P<letters>[a-zA-Z]+)').match('123 abc')
+
+      expect(md.deconstruct_keys([:numbers, :letters, :punctuation])).to eq({})
+    end
+
+    it "returns an empty hash if there are no named capturing groups" do
+      md = RE2::Regexp.new('(\d+) ([a-zA-Z]+)').match('123 abc')
+
+      expect(md.deconstruct_keys(nil)).to eq({})
+    end
+
+    it "raises an error if given a non-array of keys" do
+      md = RE2::Regexp.new('(?P<numbers>\d+) (?P<letters>[a-zA-Z]+)').match('123 abc')
+
+      expect { md.deconstruct_keys(0) }.to raise_error(TypeError)
+    end
+
+    it "raises an error if given keys as non-symbols" do
+      md = RE2::Regexp.new('(?P<numbers>\d+) (?P<letters>[a-zA-Z]+)').match('123 abc')
+
+      expect { md.deconstruct_keys([0]) }.to raise_error(TypeError)
+    end
+  end
 end

data/spec/re2/set_spec.rb

@@ -0,0 +1,168 @@
+RSpec.describe RE2::Set do
+  describe "#initialize" do
+    it "returns an instance given no args" do
+      set = RE2::Set.new
+
+      expect(set).to be_a(RE2::Set)
+    end
+
+    it "returns an instance given only an anchor of :unanchored" do
+      set = RE2::Set.new(:unanchored)
+
+      expect(set).to be_a(RE2::Set)
+    end
+
+    it "returns an instance given only an anchor of :anchor_start" do
+      set = RE2::Set.new(:anchor_start)
+
+      expect(set).to be_a(RE2::Set)
+    end
+
+    it "returns an instance given only an anchor of :anchor_both" do
+      set = RE2::Set.new(:anchor_both)
+
+      expect(set).to be_a(RE2::Set)
+    end
+
+    it "returns an instance given an anchor and options" do
+      set = RE2::Set.new(:unanchored, :case_sensitive => false)
+
+      expect(set).to be_a(RE2::Set)
+    end
+
+    it "raises an error if given an inappropriate type" do
+      expect { RE2::Set.new(0) }.to raise_error(TypeError)
+    end
+
+    it "raises an error if given an invalid anchor" do
+      expect { RE2::Set.new(:not_a_valid_anchor) }.to raise_error(
+        ArgumentError,
+        "anchor should be one of: :unanchored, :anchor_start, :anchor_both"
+      )
+    end
+  end
+
+  describe "#add" do
+    it "allows multiple patterns to be added", :aggregate_failures do
+      set = RE2::Set.new
+
+      expect(set.add("abc")).to eq(0)
+      expect(set.add("def")).to eq(1)
+      expect(set.add("ghi")).to eq(2)
+    end
+
+    it "rejects invalid patterns when added" do
+      set = RE2::Set.new(:unanchored, :log_errors => false)
+
+      expect { set.add("???") }.to raise_error(ArgumentError, /str rejected by RE2::Set->Add()/)
+    end
+
+    it "raises an error if called after #compile" do
+      set = RE2::Set.new(:unanchored, :log_errors => false)
+      set.add("abc")
+      set.compile
+
+      silence_stderr do
+        expect { set.add("def") }.to raise_error(ArgumentError)
+      end
+    end
+
+    it "raises an error if given a non-string pattern" do
+      set = RE2::Set.new(:unanchored, :log_errors => false)
+
+      expect { set.add(0) }.to raise_error(TypeError)
+    end
+  end
+
+  describe "#compile" do
+    it "compiles the set without error" do
+      set = RE2::Set.new
+      set.add("abc")
+      set.add("def")
+      set.add("ghi")
+
+      expect(set.compile).to be_truthy
+    end
+  end
+
+  describe "#match" do
+    it "matches against multiple patterns" do
+      set = RE2::Set.new
+      set.add("abc")
+      set.add("def")
+      set.add("ghi")
+      set.compile
+
+      expect(set.match("abcdefghi", :exception => false)).to eq([0, 1, 2])
+    end
+
+    it "raises an error if called before #compile by default" do
+      skip "Underlying RE2::Set::Match does not output error information" unless RE2::Set.match_raises_errors?
+
+      set = RE2::Set.new(:unanchored, :log_errors => false)
+
+      silence_stderr do
+        expect { set.match("") }.to raise_error(RE2::Set::MatchError)
+      end
+    end
+
+    it "raises an error if called before #compile when :exception is true" do
+      skip "Underlying RE2::Set::Match does not output error information" unless RE2::Set.match_raises_errors?
+
+      set = RE2::Set.new(:unanchored, :log_errors => false)
+
+      silence_stderr do
+        expect { set.match("", :exception => true) }.to raise_error(RE2::Set::MatchError)
+      end
+    end
+
+    it "returns an empty array if called before #compile when :exception is false" do
+      set = RE2::Set.new(:unanchored, :log_errors => false)
+
+      silence_stderr do
+        expect(set.match("", :exception => false)).to be_empty
+      end
+    end
+
+    it "raises an error if :exception is true and re2 does not support it" do
+      skip "Underlying RE2::Set::Match outputs error information" if RE2::Set.match_raises_errors?
+
+      set = RE2::Set.new(:unanchored, :log_errors => false)
+
+      silence_stderr do
+        expect { set.match("", :exception => true) }.to raise_error(RE2::Set::UnsupportedError)
+      end
+    end
+
+    it "raises an error if given non-hash options" do
+      set = RE2::Set.new
+
+      expect { set.match("", 0) }.to raise_error(TypeError)
+    end
+  end
+
+  def silence_stderr
+    original_stream = STDERR
+
+    if File.const_defined?(:NULL)
+      STDERR.reopen(File::NULL)
+    else
+      platform = RUBY_PLATFORM == 'java' ? RbConfig::CONFIG['host_os'] : RUBY_PLATFORM
+
+      case platform
+      when /mswin|mingw/i
+        STDERR.reopen('NUL')
+      when /amiga/i
+        STDERR.reopen('NIL')
+      when /openvms/i
+        STDERR.reopen('NL:')
+      else
+        STDERR.reopen('/dev/null')
+      end
+    end
+
+    yield
+  ensure
+    STDERR.reopen(original_stream)
+  end
+end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: re2
 version: !ruby/object:Gem::Version
-  version: 1.4.0
+  version: 1.6.0
 platform: ruby
 authors:
 - Paul Mucur
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2021-03-29 00:00:00.000000000 Z
+date: 2022-10-22 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rake-compiler
@@ -57,6 +57,7 @@ files:
 - spec/re2/match_data_spec.rb
 - spec/re2/regexp_spec.rb
 - spec/re2/scanner_spec.rb
+- spec/re2/set_spec.rb
 - spec/re2/string_spec.rb
 - spec/re2_spec.rb
 - spec/spec_helper.rb
@@ -79,7 +80,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.2.3
+rubygems_version: 3.3.7
 signing_key:
 specification_version: 4
 summary: Ruby bindings to re2.
@@ -90,4 +91,5 @@ test_files:
 - spec/re2/regexp_spec.rb
 - spec/re2/match_data_spec.rb
 - spec/re2/string_spec.rb
+- spec/re2/set_spec.rb
 - spec/re2/scanner_spec.rb