re2 0.0.4 → 0.1.0

data/README.md

@@ -12,6 +12,11 @@ If you are using a packaged Ruby distribution, make sure you also have the Ruby
 
 You can then install the library via RubyGems with `gem install re2` or `gem install re2 -- --with-re2-dir=/opt/local/re2` if re2 is not installed in the default location of `/usr/local/`.
 
+Documentation
+-------------
+
+Full documentation automatically generated from the latest version is available at <http://rdoc.info/projects/mudge/re2> and <http://yardoc.org/docs/mudge-re2/>.
+
 Usage
 -----
 
@@ -55,12 +60,10 @@ Features
 
 * Escaping regular expressions with [`RE2::Regexp.escape(unquoted)`](http://code.google.com/p/re2/source/browse/re2/re2.h#377), `RE2::Regexp.quote(unquoted)` or `RE2::QuoteMeta(unquoted)`
 
-re2.cc should be well-documented so feel free to consult this file to see what can currently be used.
-
 Contact
 -------
 
-All feedback should go to the mailing list: ruby.re2@librelist.com
+All feedback should go to the mailing list: <mailto:ruby.re2@librelist.com>
 
   [re2]: http://code.google.com/p/re2/
   [gcc]: http://gcc.gnu.org/
@@ -68,4 +71,3 @@ All feedback should go to the mailing list: ruby.re2@librelist.com
   [build-essential]: http://packages.debian.org/build-essential
   [Regexp]: http://ruby-doc.org/core/classes/Regexp.html
   [MatchData]: http://ruby-doc.org/core/classes/MatchData.html 
-

data/ext/re2/re2.cc

@@ -67,11 +67,10 @@ extern "C" {
   }
 
   /*
-   * call-seq:
-   *   match.string  -> string
-   *
    * Returns a frozen copy of the string passed into +match+.
    *
+   * @return [String] a frozen copy of the passed string.
+   * @example
    *   m = RE2('(\d+)').match("bob 123")
    *   m.string  #=> "bob 123"
    */
@@ -85,15 +84,13 @@ extern "C" {
   }
 
   /*
-   * call-seq:
-   *   match.size    -> integer
-   *   match.length  -> integer
-   *
    * Returns the number of elements in the match array (including nils).
    *
+   * @return [Fixnum] the number of elements
+   * @example
    *   m = RE2('(\d+)').match("bob 123")
-   *   m.length    #=> 2
    *   m.size      #=> 2
+   *   m.length    #=> 2
    */
   static VALUE
   re2_matchdata_size(VALUE self)
@@ -105,11 +102,10 @@ extern "C" {
   }
 
   /*
-   * call-seq:
-   *   match.regexp   -> RE2::Regexp
-   *
-   * Return the RE2::Regexp used in the match.
+   * Returns the {RE2::Regexp} used in the match.
    *
+   * @return [RE2::Regexp] the regexp used in the match
+   * @example
    *   m = RE2('(\d+)').match("bob 123")
    *   m.regexp    #=> #<RE2::Regexp /(\d+)/>
    */
@@ -129,11 +125,10 @@ extern "C" {
   }
 
   /*
-   * call-seq:
-   *   match.to_a    -> array
-   *
    * Returns the array of matches.
    *
+   * @return [Array<String, nil>] the array of matches
+   * @example
    *   m = RE2('(\d+)').match("bob 123")
    *   m.to_a    #=> ["123", "123"]
    */
@@ -168,18 +163,37 @@ extern "C" {
   }
 
   /*
-   * call-seq:
-   *   match[i]              -> string
-   *   match[start, length]  -> array
-   *   match[range]          -> array
+   * Retrieve zero, one or more matches by index.
    *
-   * Access the match data as an array.
+   * @return [Array<String, nil>, String, Boolean]
    *
-   *   m = RE2('(\d+)').match("bob 123")
-   *   m[0]      #=> "123"
-   *   m[0, 1]   #=> ["123"]
-   *   m[0...1]  #=> ["123"]
-   *   m[0..1]   #=> ["123", "123"]
+   * @overload [](index)
+   *   Access a particular match by index.
+   *
+   *   @param [Fixnum] index the index of the match to fetch
+   *   @return [String, nil] the specified match
+   *   @example
+   *     m = RE2('(\d+)').match("bob 123")
+   *     m[0]    #=> "123"
+   *
+   * @overload [](start, length)
+   *   Access a range of matches by starting index and length.
+   *
+   *   @param [Fixnum] start the index from which to start
+   *   @param [Fixnum] length the number of elements to fetch
+   *   @return [Array<String, nil>] the specified matches
+   *   @example
+   *     m = RE2('(\d+)').match("bob 123")
+   *     m[0, 1]    #=> ["123"]
+   *
+   * @overload [](range)
+   *   Access a range of matches by index.
+   *
+   *   @param [Range] range the range of match indexes to fetch
+   *   @return [Array<String, nil>] the specified matches
+   *   @example
+   *     m = RE2('(\d+)').match("bob 123")
+   *     m[0..1]    #=> "[123", "123"]
    */
   static VALUE
   re2_matchdata_aref(int argc, VALUE *argv, VALUE self)
@@ -195,10 +209,9 @@ extern "C" {
   }
 
   /*
-   * call-seq:
-   *   match.to_s    -> string
-   *
    * Returns the entire matched string.
+   *
+   * @return [String] the entire matched string
    */
   static VALUE
   re2_matchdata_to_s(VALUE self)
@@ -207,11 +220,10 @@ extern "C" {
   }
 
   /*
-   * call-seq:
-   *   match.inspect   -> string
-   *
    * Returns a printable version of the match.
    *
+   * @return [String] a printable version of the match
+   * @example
    *   m = RE2('(\d+)').match("bob 123")
    *   m.inspect    #=> "#<RE2::MatchData \"123\" 1:\"123\">"
    */
@@ -224,38 +236,40 @@ extern "C" {
 
     Data_Get_Struct(self, re2_matchdata, m);
 
-    result = rb_str_buf_new2("#<RE2::MatchData");
+    result = rb_str_new2("#<RE2::MatchData");
 
     for (i = 0; i < m->number_of_matches; i++) {
-      rb_str_buf_cat2(result, " ");
+      rb_str_cat2(result, " ");
 
       if (i > 0) {
         char buf[sizeof(i)*3+1];
         snprintf(buf, sizeof(buf), "%d", i);
-        rb_str_buf_cat2(result, buf);
-        rb_str_buf_cat2(result, ":");
+        rb_str_cat2(result, buf);
+        rb_str_cat2(result, ":");
       }
 
       match = re2_matchdata_nth_match(i, self);
 
       if (match == Qnil) {
-        rb_str_buf_cat2(result, "nil");
+        rb_str_cat2(result, "nil");
       } else {
-        rb_str_buf_append(result, rb_str_inspect(match));
+        rb_str_append(result, rb_str_inspect(match));
       }
     }
-    rb_str_buf_cat2(result, ">");
+    rb_str_cat2(result, ">");
 
     return result;
   }
 
   /*
-   * call-seq:
-   *   RE2(pattern)                  -> re2
-   *   RE2(pattern, options)         -> re2
-   *
    * Returns a new RE2 object with a compiled version of
    * +pattern+ stored inside. Equivalent to +RE2.new+.
+   *
+   * @return [RE2::Regexp] an RE2::Regexp with the specified pattern and options
+   * @param [String] pattern the pattern to compile
+   * @param [Hash] options the options to compile a regexp with
+   * @see RE2::Regexp.new
+   *
    */
   static VALUE
   re2_re2(int argc, VALUE *argv, VALUE self)
@@ -265,49 +279,38 @@ extern "C" {
   }
 
   /*
-   * call-seq:
-   *   RE2::Regexp.new(pattern)               -> re2
-   *   RE2::Regexp.new(pattern, options)      -> re2
-   *   RE2::Regexp.compile(pattern)           -> re2
-   *   RE2::Regexp.compile(pattern, options)  -> re2
-   *
-   * Returns a new RE2 object with a compiled version of
+   * Returns a new {RE2::Regexp} object with a compiled version of
    * +pattern+ stored inside.
    *
-   * Options can be a hash with the following keys:
-   *
-   *   :utf8           - text and pattern are UTF-8; otherwise 
-   *                     Latin-1 (default true)
-   *
-   *   :posix_syntax   - restrict regexps to POSIX egrep syntax
-   *                     (default false)
-   *
-   *   :longest_match  - search for longest match, not first match
-   *                     (default false)
-   *
-   *   :log_errors     - log syntax and execution errors to ERROR
-   *                     (default true)
-   *
-   *   :max_mem        - approx. max memory footprint of RE2
-   *
-   *   :literal        - interpret string as literal, not regexp
-   *                     (default false)
-   *
-   *   :never_nl       - never match \n, even if it is in regexp
-   *                     (default false)
-   *
-   *   :case_sensitive - match is case-sensitive (regexp can override
-   *                     with (?i) unless in posix_syntax mode)
-   *                     (default true)
-   *
-   *   :perl_classes   - allow Perl's \d \s \w \D \S \W when in
-   *                     posix_syntax mode (default false)
-   *
-   *   :word_boundary  - allow \b \B (word boundary and not) when
-   *                     in posix_syntax mode (default false)
-   *
-   *   :one_line       - ^ and $ only match beginning and end of text
-   *                     when in posix_syntax mode (default false)
+   * @return [RE2::Regexp]
+   *
+   * @overload initialize(pattern)
+   *   Returns a new {RE2::Regexp} object with a compiled version of
+   *   +pattern+ stored inside with the default options.
+   *
+   *   @param [String] pattern the pattern to compile
+   *   @return [RE2::Regexp] an RE2::Regexp with the specified pattern
+   *   @raise [NoMemoryError] if memory could not be allocated for the compiled pattern
+   *
+   * @overload initialize(pattern, options)
+   *   Returns a new {RE2::Regexp} object with a compiled version of
+   *   +pattern+ stored inside with the specified options.
+   *
+   *   @param [String] pattern the pattern to compile
+   *   @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::Regexp] an RE2::Regexp with the specified pattern and options
+   *   @raise [NoMemoryError] if memory could not be allocated for the compiled pattern
    */
   static VALUE
   re2_regexp_initialize(int argc, VALUE *argv, VALUE self)
@@ -395,11 +398,10 @@ extern "C" {
   }
 
   /*
-   * call-seq:
-   *   re2.inspect   -> string
-   *
    * Returns a printable version of the regular expression +re2+.
    *
+   * @return [String] a printable version of the regular expression
+   * @example
    *   re2 = RE2::Regexp.new("woo?")
    *   re2.inspect    #=> "#<RE2::Regexp /woo?/>"
    */
@@ -407,25 +409,20 @@ extern "C" {
   re2_regexp_inspect(VALUE self)
   {
     re2_pattern *p;
-    VALUE result = rb_str_buf_new2("#<RE2::Regexp /");
+    VALUE result = rb_str_new2("#<RE2::Regexp /");
 
     Data_Get_Struct(self, re2_pattern, p);
-    rb_str_buf_cat2(result, p->pattern->pattern().c_str());
-    rb_str_buf_cat2(result, "/>");
+    rb_str_cat2(result, p->pattern->pattern().c_str());
+    rb_str_cat2(result, "/>");
 
     return result;
   }
 
   /*
-   * call-seq:
-   *   re2.to_s       -> string
-   *   re2.to_str     -> string
-   *   re2.pattern    -> string
-   *   re2.source     -> string
-   *   re2.inspect    -> string
-   *
    * Returns a string version of the regular expression +re2+.
    *
+   * @return [String] a string version of the regular expression
+   * @example
    *   re2 = RE2::Regexp.new("woo?")
    *   re2.to_s    #=> "woo?"
    */
@@ -438,12 +435,11 @@ extern "C" {
   }
 
   /*
-   * call-seq:
-   *   re2.ok?    -> true or false
-   *
    * Returns whether or not the regular expression +re2+
    * was compiled successfully or not.
    *
+   * @return [Boolean] whether or not compilation was successful
+   * @example
    *   re2 = RE2::Regexp.new("woo?")
    *   re2.ok?    #=> true
    */
@@ -456,12 +452,11 @@ extern "C" {
   }
 
   /*
-   * call-seq:
-   *   re2.utf8?    -> true or false
-   *
    * Returns whether or not the regular expression +re2+
    * was compiled with the utf8 option set to true.
    *
+   * @return [Boolean] the utf8 option
+   * @example
    *   re2 = RE2::Regexp.new("woo?", :utf8 => true)
    *   re2.utf8?    #=> true
    */
@@ -474,12 +469,11 @@ extern "C" {
   }
 
   /*
-   * call-seq:
-   *   re2.posix_syntax?    -> true or false
-   *
    * Returns whether or not the regular expression +re2+
    * was compiled with the posix_syntax option set to true.
    *
+   * @return [Boolean] the posix_syntax option
+   * @example
    *   re2 = RE2::Regexp.new("woo?", :posix_syntax => true)
    *   re2.posix_syntax?    #=> true
    */
@@ -492,12 +486,11 @@ extern "C" {
   }
 
   /*
-   * call-seq:
-   *   re2.longest_match?    -> true or false
-   *
    * Returns whether or not the regular expression +re2+
    * was compiled with the longest_match option set to true.
    *
+   * @return [Boolean] the longest_match option
+   * @example
    *   re2 = RE2::Regexp.new("woo?", :longest_match => true)
    *   re2.longest_match?    #=> true
    */
@@ -510,12 +503,11 @@ extern "C" {
   }
 
   /*
-   * call-seq:
-   *   re2.log_errors?    -> true or false
-   *
    * Returns whether or not the regular expression +re2+
    * was compiled with the log_errors option set to true.
    *
+   * @return [Boolean] the log_errors option
+   * @example
    *   re2 = RE2::Regexp.new("woo?", :log_errors => true)
    *   re2.log_errors?    #=> true
    */
@@ -528,12 +520,11 @@ extern "C" {
   }
 
   /*
-   * call-seq:
-   *   re2.max_mem    -> int
-   *
    * Returns the max_mem setting for the regular expression
    * +re2+.
    *
+   * @return [Fixnum] the max_mem option
+   * @example
    *   re2 = RE2::Regexp.new("woo?", :max_mem => 1024)
    *   re2.max_mem    #=> 1024
    */
@@ -546,12 +537,11 @@ extern "C" {
   }
 
   /*
-   * call-seq:
-   *   re2.literal?    -> true or false
-   *
    * Returns whether or not the regular expression +re2+
    * was compiled with the literal option set to true.
    *
+   * @return [Boolean] the literal option
+   * @example
    *   re2 = RE2::Regexp.new("woo?", :literal => true)
    *   re2.literal?    #=> true
    */
@@ -564,12 +554,11 @@ extern "C" {
   }
 
   /*
-   * call-seq:
-   *   re2.never_nl?    -> true or false
-   *
    * Returns whether or not the regular expression +re2+
    * was compiled with the never_nl option set to true.
    *
+   * @return [Boolean] the never_nl option
+   * @example
    *   re2 = RE2::Regexp.new("woo?", :never_nl => true)
    *   re2.never_nl?    #=> true
    */
@@ -582,12 +571,11 @@ extern "C" {
   }
 
   /*
-   * call-seq:
-   *   re2.case_sensitive?    -> true or false
-   *
    * Returns whether or not the regular expression +re2+
    * was compiled with the case_sensitive option set to true.
    *
+   * @return [Boolean] the case_sensitive option
+   * @example
    *   re2 = RE2::Regexp.new("woo?", :case_sensitive => true)
    *   re2.case_sensitive?    #=> true
    */
@@ -600,15 +588,14 @@ extern "C" {
   }
 
   /*
-   * call-seq:
-   *   re2.case_insensitive?    -> true or false
-   *   re2.casefold?            -> true or false
-   *
    * Returns whether or not the regular expression +re2+
    * was compiled with the case_sensitive option set to false.
    *
+   * @return [Boolean] the inverse of the case_sensitive option
+   * @example
    *   re2 = RE2::Regexp.new("woo?", :case_sensitive => true)
    *   re2.case_insensitive?    #=> false
+   *   re2.casefold?    #=> false
    */
   static VALUE
   re2_regexp_case_insensitive(VALUE self)
@@ -617,12 +604,11 @@ extern "C" {
   }
 
   /*
-   * call-seq:
-   *   re2.perl_classes?    -> true or false
-   *
    * Returns whether or not the regular expression +re2+
    * was compiled with the perl_classes option set to true.
    *
+   * @return [Boolean] the perl_classes option
+   * @example
    *   re2 = RE2::Regexp.new("woo?", :perl_classes => true)
    *   re2.perl_classes?    #=> true
    */
@@ -635,12 +621,11 @@ extern "C" {
   }
 
   /*
-   * call-seq:
-   *   re2.word_boundary?    -> true or false
-   *
    * Returns whether or not the regular expression +re2+
    * was compiled with the word_boundary option set to true.
    *
+   * @return [Boolean] the word_boundary option
+   * @example
    *   re2 = RE2::Regexp.new("woo?", :word_boundary => true)
    *   re2.word_boundary?    #=> true
    */
@@ -653,12 +638,11 @@ extern "C" {
   }
 
   /*
-   * call-seq:
-   *   re2.one_line?    -> true or false
-   *
    * Returns whether or not the regular expression +re2+
    * was compiled with the one_line option set to true.
    *
+   * @return [Boolean] the one_line option
+   * @example
    *   re2 = RE2::Regexp.new("woo?", :one_line => true)
    *   re2.one_line?    #=> true
    */
@@ -671,11 +655,10 @@ extern "C" {
   }
 
   /*
-   * call-seq:
-   *   re2.error    -> error_str
-   *
    * If the RE2 could not be created properly, returns an
    * error string.
+   *
+   * @return [String] the error string
    */
   static VALUE
   re2_regexp_error(VALUE self)
@@ -686,11 +669,10 @@ extern "C" {
   }
 
   /*
-   * call-seq:
-   *   re2.error_arg    -> error_str
-   *
    * If the RE2 could not be created properly, returns
    * the offending portion of the regexp.
+   *
+   * @return [String] the offending portion of the regexp
    */
   static VALUE
   re2_regexp_error_arg(VALUE self)
@@ -701,12 +683,11 @@ extern "C" {
   }
 
   /*
-   * call-seq:
-   *   re2.program_size    -> size
-   *
    * Returns the program size, a very approximate measure
    * of a regexp's "cost". Larger numbers are more expensive
    * than smaller numbers.
+   *
+   * @return [Fixnum] the regexp "cost"
    */
   static VALUE
   re2_regexp_program_size(VALUE self)
@@ -717,11 +698,10 @@ extern "C" {
   }
 
   /*
-   * call-seq:
-   *   re2.options    -> options_hash
-   *
    * Returns a hash of the options currently set for
    * +re2+.
+   *
+   * @return [Hash] the options
    */
   static VALUE
   re2_regexp_options(VALUE self)
@@ -765,19 +745,18 @@ extern "C" {
     rb_hash_aset(options, ID2SYM(id_one_line),
         BOOL2RUBY(p->pattern->options().one_line()));
 
-    // This is a read-only hash after all...
+    /* This is a read-only hash after all... */
     OBJ_FREEZE(options);
 
     return options;
   }
 
   /*
-   * call-seq:
-   *   re2.number_of_capturing_groups    -> int
-   *
    * Returns the number of capturing subpatterns, or -1 if the regexp
    * wasn't valid on construction. The overall match ($0) does not
    * count: if the regexp is "(a)(b)", returns 2.
+   *
+   * @return [Fixnum] the number of capturing subpatterns
    */
   static VALUE
   re2_regexp_number_of_capturing_groups(VALUE self)
@@ -789,24 +768,48 @@ extern "C" {
   }
 
   /*
-   * call-seq:
-   *   re2.match(text)                 -> [match, match]
-   *   re2.match(text, 0)              -> true or false
-   *   re2.match(text, num_of_matches) -> [match, match]
-   *
-   * Looks for the pattern in +re2+ in +text+; when specified
-   * without a second argument, will return an array of the matching
-   * pattern and all subpatterns. If the second argument is 0, a
-   * simple true or false will be returned to indicate a successful
-   * match. If the second argument is any integer greater than 0,
-   * that number of matches will be returned (padded with nils if
-   * there are insufficient matches).
-   *
-   *   r = RE2::Regexp.new('w(o)(o)')
-   *   r.match('woo')    #=> ["woo", "o", "o"]
-   *   r.match('woo', 0) #=> true
-   *   r.match('bob', 0) #=> false
-   *   r.match('woo', 1) #=> ["woo", "o"]
+   * Match the pattern against the given +text+ and return either
+   * a boolean (if no submatches are required) or a {RE2::MatchData}
+   * instance.
+   *
+   * @return [Boolean, RE2::MatchData]
+   *
+   * @overload match(text)
+   *   Returns an {RE2::MatchData} containing the matching
+   *   pattern and all subpatterns resulting from looking for
+   *   the regexp in +text+.
+   *
+   *   @param [String] text the text to search
+   *   @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)')
+   *     r.match('woo)    #=> #<RE2::MatchData "woo" 1:"o" 2:"o">
+   *
+   * @overload match(text, 0)
+   *   Returns either true or false indicating whether a
+   *   successful match was made.
+   *
+   *   @param [String] text the text to search
+   *   @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)')
+   *     r.match('woo', 0) #=> true
+   *     r.match('bob', 0) #=> false
+   *
+   * @overload match(text, number_of_matches)
+   *   See +match(text)+ but with a specific number of
+   *   matches returned (padded with nils if necessary).
+   *
+   *   @param [String] text the text to search
+   *   @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)')
+   *     r.match('woo', 1) #=> #<RE2::MatchData "woo" 1:"o">
+   *     r.match('woo', 3) #=> #<RE2::MatchData "woo" 1:"o" 2:"o" 3:nil>
    */
   static VALUE
   re2_regexp_match(int argc, VALUE *argv, VALUE self)
@@ -860,12 +863,10 @@ extern "C" {
   }
 
   /*
-   * call-seq:
-   *   re2.match?(text)  -> true or false
-   *   re2 =~ text  -> true or false
-   *
    * Returns true or false to indicate a successful match.
    * Equivalent to +re2.match(text, 0)+.
+   *
+   * @return [Boolean] whether the match was successful
    */
   static VALUE
   re2_regexp_match_query(VALUE self, VALUE text)
@@ -878,12 +879,13 @@ extern "C" {
   }
 
   /*
-   * call-seq:
-   *   RE2::Replace(str, pattern, rewrite)    -> str
-   *
    * Replaces the first occurrence +pattern+ in +str+ with 
    * +rewrite+ <i>in place</i>.
    *
+   * @param [String] str the string to modify
+   * @param [String, RE2::Regexp] pattern a regexp matching text to be replaced
+   * @param [String] rewrite the string to replace with
+   * @example
    *   RE2::Replace("hello there", "hello", "howdy") #=> "howdy there"
    *   re2 = RE2.new("hel+o")
    *   RE2::Replace("hello there", re2, "yo")        #=> "yo there"
@@ -898,11 +900,11 @@ extern "C" {
     VALUE repl;
     re2_pattern *p;
 
-    // Convert all the inputs to be pumped into RE2::Replace.
+    /* Convert all the inputs to be pumped into RE2::Replace. */
     std::string str_as_string(StringValuePtr(str));
     re2::StringPiece rewrite_as_string_piece(StringValuePtr(rewrite));
 
-    // Do the replacement.
+    /* Do the replacement. */
     if (rb_obj_is_kind_of(pattern, re2_cRegexp)) {
       Data_Get_Struct(pattern, re2_pattern, p);
       RE2::Replace(&str_as_string, *p->pattern, rewrite_as_string_piece);
@@ -910,22 +912,23 @@ extern "C" {
       RE2::Replace(&str_as_string, StringValuePtr(pattern), rewrite_as_string_piece);
     }
 
-    // Save the replacement as a VALUE.
+    /* Save the replacement as a VALUE. */
     repl = rb_str_new(str_as_string.c_str(), str_as_string.length());
 
-    // Replace the original string with the replacement.
+    /* Replace the original string with the replacement. */
     rb_str_update(str, 0, RSTRING_LEN(str), repl);
 
     return str;
   }
 
   /*
-   * call-seq:
-   *   RE2::GlobalReplace(str, pattern, rewrite)    -> str
-   *
    * Replaces every occurrence of +pattern+ in +str+ with 
    * +rewrite+ <i>in place</i>.
    *
+   * @param [String] str the string to modify
+   * @param [String, RE2::Regexp] pattern a regexp matching text to be replaced
+   * @param [String] rewrite the string to replace with
+   * @example
    *   RE2::GlobalReplace("hello there", "e", "i")   #=> "hillo thiri"
    *   re2 = RE2.new("oo?")
    *   RE2::GlobalReplace("whoops-doops", re2, "e")  #=> "wheps-deps"
@@ -938,13 +941,13 @@ extern "C" {
   {
     UNUSED(self);
 
-    // Convert all the inputs to be pumped into RE2::GlobalReplace.
+    /* Convert all the inputs to be pumped into RE2::GlobalReplace. */
     re2_pattern *p;
     std::string str_as_string(StringValuePtr(str));
     re2::StringPiece rewrite_as_string_piece(StringValuePtr(rewrite));
     VALUE repl;
 
-    // Do the replacement.
+    /* Do the replacement. */
     if (rb_obj_is_kind_of(pattern, re2_cRegexp)) {
       Data_Get_Struct(pattern, re2_pattern, p);
       RE2::GlobalReplace(&str_as_string, *p->pattern, rewrite_as_string_piece);
@@ -952,26 +955,24 @@ extern "C" {
       RE2::GlobalReplace(&str_as_string, StringValuePtr(pattern), rewrite_as_string_piece);
     }
 
-    // Save the replacement as a VALUE.
+    /* Save the replacement as a VALUE. */
     repl = rb_str_new(str_as_string.c_str(), str_as_string.length());
 
-    // Replace the original string with the replacement.
+    /* Replace the original string with the replacement. */
     rb_str_update(str, 0, RSTRING_LEN(str), repl);
 
     return str;
   }
 
   /*
-   * call-seq:
-   *   RE2::QuoteMeta(str)    -> str
-   *   RE2::Regexp.escape(str)        -> str
-   *   RE2::Regexp.quote(str)         -> str
-   *
    * Returns a version of str with all potentially meaningful regexp
    * characters escaped. The returned string, used as a regular
    * expression, will exactly match the original string.
    *
-   *   RE2::QuoteMeta("1.5-2.0?")    #=> "1\.5\-2\.0\?"
+   * @param [String] unquoted the unquoted string
+   * @return [String] the escaped string
+   * @example
+   *   RE2::Regexp.escape("1.5-2.0?")    #=> "1\.5\-2\.0\?"
    */
   static VALUE
   re2_QuoteMeta(VALUE self, VALUE unquoted)
@@ -991,53 +992,53 @@ extern "C" {
     rb_define_alloc_func(re2_cRegexp, (VALUE (*)(VALUE))re2_regexp_allocate);
     rb_define_alloc_func(re2_cMatchData, (VALUE (*)(VALUE))re2_matchdata_allocate);
 
-    rb_define_method(re2_cMatchData, "string", (VALUE (*)(...))re2_matchdata_string, 0);
-    rb_define_method(re2_cMatchData, "regexp", (VALUE (*)(...))re2_matchdata_regexp, 0);
-    rb_define_method(re2_cMatchData, "to_a", (VALUE (*)(...))re2_matchdata_to_a, 0);
-    rb_define_method(re2_cMatchData, "size", (VALUE (*)(...))re2_matchdata_size, 0);
-    rb_define_method(re2_cMatchData, "length", (VALUE (*)(...))re2_matchdata_size, 0);
-    rb_define_method(re2_cMatchData, "[]", (VALUE (*)(...))re2_matchdata_aref, -1);
-    rb_define_method(re2_cMatchData, "to_s", (VALUE (*)(...))re2_matchdata_to_s, 0);
-    rb_define_method(re2_cMatchData, "inspect", (VALUE (*)(...))re2_matchdata_inspect, 0);
-
-    rb_define_method(re2_cRegexp, "initialize", (VALUE (*)(...))re2_regexp_initialize, -1);
-    rb_define_method(re2_cRegexp, "ok?", (VALUE (*)(...))re2_regexp_ok, 0);
-    rb_define_method(re2_cRegexp, "error", (VALUE (*)(...))re2_regexp_error, 0);
-    rb_define_method(re2_cRegexp, "error_arg", (VALUE (*)(...))re2_regexp_error_arg, 0);
-    rb_define_method(re2_cRegexp, "program_size", (VALUE (*)(...))re2_regexp_program_size, 0);
-    rb_define_method(re2_cRegexp, "options", (VALUE (*)(...))re2_regexp_options, 0);
-    rb_define_method(re2_cRegexp, "number_of_capturing_groups", (VALUE (*)(...))re2_regexp_number_of_capturing_groups, 0);
-    rb_define_method(re2_cRegexp, "match", (VALUE (*)(...))re2_regexp_match, -1);
-    rb_define_method(re2_cRegexp, "match?", (VALUE (*)(...))re2_regexp_match_query, 1);
-    rb_define_method(re2_cRegexp, "=~", (VALUE (*)(...))re2_regexp_match_query, 1);
-    rb_define_method(re2_cRegexp, "===", (VALUE (*)(...))re2_regexp_match_query, 1);
-    rb_define_method(re2_cRegexp, "to_s", (VALUE (*)(...))re2_regexp_to_s, 0);
-    rb_define_method(re2_cRegexp, "to_str", (VALUE (*)(...))re2_regexp_to_s, 0);
-    rb_define_method(re2_cRegexp, "pattern", (VALUE (*)(...))re2_regexp_to_s, 0);
-    rb_define_method(re2_cRegexp, "source", (VALUE (*)(...))re2_regexp_to_s, 0);
-    rb_define_method(re2_cRegexp, "inspect", (VALUE (*)(...))re2_regexp_inspect, 0);
-    rb_define_method(re2_cRegexp, "utf8?", (VALUE (*)(...))re2_regexp_utf8, 0);
-    rb_define_method(re2_cRegexp, "posix_syntax?", (VALUE (*)(...))re2_regexp_posix_syntax, 0);
-    rb_define_method(re2_cRegexp, "longest_match?", (VALUE (*)(...))re2_regexp_longest_match, 0);
-    rb_define_method(re2_cRegexp, "log_errors?", (VALUE (*)(...))re2_regexp_log_errors, 0);
-    rb_define_method(re2_cRegexp, "max_mem", (VALUE (*)(...))re2_regexp_max_mem, 0);
-    rb_define_method(re2_cRegexp, "literal?", (VALUE (*)(...))re2_regexp_literal, 0);
-    rb_define_method(re2_cRegexp, "never_nl?", (VALUE (*)(...))re2_regexp_never_nl, 0);
-    rb_define_method(re2_cRegexp, "case_sensitive?", (VALUE (*)(...))re2_regexp_case_sensitive, 0);
-    rb_define_method(re2_cRegexp, "case_insensitive?", (VALUE (*)(...))re2_regexp_case_insensitive, 0);
-    rb_define_method(re2_cRegexp, "casefold?", (VALUE (*)(...))re2_regexp_case_insensitive, 0);
-    rb_define_method(re2_cRegexp, "perl_classes?", (VALUE (*)(...))re2_regexp_perl_classes, 0);
-    rb_define_method(re2_cRegexp, "word_boundary?", (VALUE (*)(...))re2_regexp_word_boundary, 0);
-    rb_define_method(re2_cRegexp, "one_line?", (VALUE (*)(...))re2_regexp_one_line, 0);
-
-    rb_define_module_function(re2_mRE2, "Replace", (VALUE (*)(...))re2_Replace, 3);
-    rb_define_module_function(re2_mRE2, "GlobalReplace", (VALUE (*)(...))re2_GlobalReplace, 3);
-    rb_define_module_function(re2_mRE2, "QuoteMeta", (VALUE (*)(...))re2_QuoteMeta, 1);
-    rb_define_singleton_method(re2_cRegexp, "escape", (VALUE (*)(...))re2_QuoteMeta, 1);
-    rb_define_singleton_method(re2_cRegexp, "quote", (VALUE (*)(...))re2_QuoteMeta, 1);
-    rb_define_singleton_method(re2_cRegexp, "compile", (VALUE (*)(...))rb_class_new_instance, -1);
-
-    rb_define_global_function("RE2", (VALUE (*)(...))re2_re2, -1);
+    rb_define_method(re2_cMatchData, "string", RUBY_METHOD_FUNC(re2_matchdata_string), 0);
+    rb_define_method(re2_cMatchData, "regexp", RUBY_METHOD_FUNC(re2_matchdata_regexp), 0);
+    rb_define_method(re2_cMatchData, "to_a", RUBY_METHOD_FUNC(re2_matchdata_to_a), 0);
+    rb_define_method(re2_cMatchData, "size", RUBY_METHOD_FUNC(re2_matchdata_size), 0);
+    rb_define_method(re2_cMatchData, "length", RUBY_METHOD_FUNC(re2_matchdata_size), 0);
+    rb_define_method(re2_cMatchData, "[]", RUBY_METHOD_FUNC(re2_matchdata_aref), -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_cRegexp, "initialize", RUBY_METHOD_FUNC(re2_regexp_initialize), -1);
+    rb_define_method(re2_cRegexp, "ok?", RUBY_METHOD_FUNC(re2_regexp_ok), 0);
+    rb_define_method(re2_cRegexp, "error", RUBY_METHOD_FUNC(re2_regexp_error), 0);
+    rb_define_method(re2_cRegexp, "error_arg", RUBY_METHOD_FUNC(re2_regexp_error_arg), 0);
+    rb_define_method(re2_cRegexp, "program_size", RUBY_METHOD_FUNC(re2_regexp_program_size), 0);
+    rb_define_method(re2_cRegexp, "options", RUBY_METHOD_FUNC(re2_regexp_options), 0);
+    rb_define_method(re2_cRegexp, "number_of_capturing_groups", RUBY_METHOD_FUNC(re2_regexp_number_of_capturing_groups), 0);
+    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);
+    rb_define_method(re2_cRegexp, "=~", RUBY_METHOD_FUNC(re2_regexp_match_query), 1);
+    rb_define_method(re2_cRegexp, "===", RUBY_METHOD_FUNC(re2_regexp_match_query), 1);
+    rb_define_method(re2_cRegexp, "to_s", RUBY_METHOD_FUNC(re2_regexp_to_s), 0);
+    rb_define_method(re2_cRegexp, "to_str", RUBY_METHOD_FUNC(re2_regexp_to_s), 0);
+    rb_define_method(re2_cRegexp, "pattern", RUBY_METHOD_FUNC(re2_regexp_to_s), 0);
+    rb_define_method(re2_cRegexp, "source", RUBY_METHOD_FUNC(re2_regexp_to_s), 0);
+    rb_define_method(re2_cRegexp, "inspect", RUBY_METHOD_FUNC(re2_regexp_inspect), 0);
+    rb_define_method(re2_cRegexp, "utf8?", RUBY_METHOD_FUNC(re2_regexp_utf8), 0);
+    rb_define_method(re2_cRegexp, "posix_syntax?", RUBY_METHOD_FUNC(re2_regexp_posix_syntax), 0);
+    rb_define_method(re2_cRegexp, "longest_match?", RUBY_METHOD_FUNC(re2_regexp_longest_match), 0);
+    rb_define_method(re2_cRegexp, "log_errors?", RUBY_METHOD_FUNC(re2_regexp_log_errors), 0);
+    rb_define_method(re2_cRegexp, "max_mem", RUBY_METHOD_FUNC(re2_regexp_max_mem), 0);
+    rb_define_method(re2_cRegexp, "literal?", RUBY_METHOD_FUNC(re2_regexp_literal), 0);
+    rb_define_method(re2_cRegexp, "never_nl?", RUBY_METHOD_FUNC(re2_regexp_never_nl), 0);
+    rb_define_method(re2_cRegexp, "case_sensitive?", RUBY_METHOD_FUNC(re2_regexp_case_sensitive), 0);
+    rb_define_method(re2_cRegexp, "case_insensitive?", RUBY_METHOD_FUNC(re2_regexp_case_insensitive), 0);
+    rb_define_method(re2_cRegexp, "casefold?", RUBY_METHOD_FUNC(re2_regexp_case_insensitive), 0);
+    rb_define_method(re2_cRegexp, "perl_classes?", RUBY_METHOD_FUNC(re2_regexp_perl_classes), 0);
+    rb_define_method(re2_cRegexp, "word_boundary?", RUBY_METHOD_FUNC(re2_regexp_word_boundary), 0);
+    rb_define_method(re2_cRegexp, "one_line?", RUBY_METHOD_FUNC(re2_regexp_one_line), 0);
+
+    rb_define_module_function(re2_mRE2, "Replace", RUBY_METHOD_FUNC(re2_Replace), 3);
+    rb_define_module_function(re2_mRE2, "GlobalReplace", RUBY_METHOD_FUNC(re2_GlobalReplace), 3);
+    rb_define_module_function(re2_mRE2, "QuoteMeta", RUBY_METHOD_FUNC(re2_QuoteMeta), 1);
+    rb_define_singleton_method(re2_cRegexp, "escape", RUBY_METHOD_FUNC(re2_QuoteMeta), 1);
+    rb_define_singleton_method(re2_cRegexp, "quote", RUBY_METHOD_FUNC(re2_QuoteMeta), 1);
+    rb_define_singleton_method(re2_cRegexp, "compile", RUBY_METHOD_FUNC(rb_class_new_instance), -1);
+
+    rb_define_global_function("RE2", RUBY_METHOD_FUNC(re2_re2), -1);
 
     /* Create the symbols used in options. */
     id_utf8 = rb_intern("utf8");
@@ -1051,5 +1052,10 @@ extern "C" {
     id_perl_classes = rb_intern("perl_classes");
     id_word_boundary = rb_intern("word_boundary");
     id_one_line = rb_intern("one_line");
+
+    #if 0
+      /* Fake so YARD generates the file. */
+      rb_mKernel = rb_define_module("Kernel");
+    #endif
   }
 }

data/test/re2_test.rb

@@ -119,6 +119,7 @@ class RE2Test < Test::Unit::TestCase
     assert_respond_to m, :[]
     assert_equal r, m.regexp
     assert_equal text, m.string
+    assert !text.frozen?
     assert m.string.frozen?
     assert_not_equal m.string.object_id, text.object_id
     assert_equal '#<RE2::MatchData "123" 1:"123">', m.inspect

metadata

@@ -1,13 +1,12 @@
 --- !ruby/object:Gem::Specification 
 name: re2
 version: !ruby/object:Gem::Version 
-  hash: 23
   prerelease: false
   segments: 
   - 0
+  - 1
   - 0
-  - 4
-  version: 0.0.4
+  version: 0.1.0
 platform: ruby
 authors: 
 - Paul Mucur
@@ -15,7 +14,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2010-08-02 00:00:00 +01:00
+date: 2010-08-28 00:00:00 +01:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
@@ -26,7 +25,6 @@ dependencies:
     requirements: 
     - - ">="
       - !ruby/object:Gem::Version 
-        hash: 3
         segments: 
         - 0
         version: "0"
@@ -61,7 +59,6 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements: 
   - - ">="
     - !ruby/object:Gem::Version 
-      hash: 3
       segments: 
       - 0
       version: "0"
@@ -70,7 +67,6 @@ required_rubygems_version: !ruby/object:Gem::Requirement
   requirements: 
   - - ">="
     - !ruby/object:Gem::Version 
-      hash: 3
       segments: 
       - 0
       version: "0"