re2 0.0.4 → 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (4) hide show
  1. data/README.md +6 -4
  2. data/ext/re2/re2.cc +247 -241
  3. data/test/re2_test.rb +1 -0
  4. metadata +3 -7
data/README.md CHANGED
@@ -12,6 +12,11 @@ If you are using a packaged Ruby distribution, make sure you also have the Ruby
12
12
 
13
13
  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/`.
14
14
 
15
+ Documentation
16
+ -------------
17
+
18
+ Full documentation automatically generated from the latest version is available at <http://rdoc.info/projects/mudge/re2> and <http://yardoc.org/docs/mudge-re2/>.
19
+
15
20
  Usage
16
21
  -----
17
22
 
@@ -55,12 +60,10 @@ Features
55
60
 
56
61
  * 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)`
57
62
 
58
- re2.cc should be well-documented so feel free to consult this file to see what can currently be used.
59
-
60
63
  Contact
61
64
  -------
62
65
 
63
- All feedback should go to the mailing list: ruby.re2@librelist.com
66
+ All feedback should go to the mailing list: <mailto:ruby.re2@librelist.com>
64
67
 
65
68
  [re2]: http://code.google.com/p/re2/
66
69
  [gcc]: http://gcc.gnu.org/
@@ -68,4 +71,3 @@ All feedback should go to the mailing list: ruby.re2@librelist.com
68
71
  [build-essential]: http://packages.debian.org/build-essential
69
72
  [Regexp]: http://ruby-doc.org/core/classes/Regexp.html
70
73
  [MatchData]: http://ruby-doc.org/core/classes/MatchData.html
71
-
data/ext/re2/re2.cc CHANGED
@@ -67,11 +67,10 @@ extern "C" {
67
67
  }
68
68
 
69
69
  /*
70
- * call-seq:
71
- * match.string -> string
72
- *
73
70
  * Returns a frozen copy of the string passed into +match+.
74
71
  *
72
+ * @return [String] a frozen copy of the passed string.
73
+ * @example
75
74
  * m = RE2('(\d+)').match("bob 123")
76
75
  * m.string #=> "bob 123"
77
76
  */
@@ -85,15 +84,13 @@ extern "C" {
85
84
  }
86
85
 
87
86
  /*
88
- * call-seq:
89
- * match.size -> integer
90
- * match.length -> integer
91
- *
92
87
  * Returns the number of elements in the match array (including nils).
93
88
  *
89
+ * @return [Fixnum] the number of elements
90
+ * @example
94
91
  * m = RE2('(\d+)').match("bob 123")
95
- * m.length #=> 2
96
92
  * m.size #=> 2
93
+ * m.length #=> 2
97
94
  */
98
95
  static VALUE
99
96
  re2_matchdata_size(VALUE self)
@@ -105,11 +102,10 @@ extern "C" {
105
102
  }
106
103
 
107
104
  /*
108
- * call-seq:
109
- * match.regexp -> RE2::Regexp
110
- *
111
- * Return the RE2::Regexp used in the match.
105
+ * Returns the {RE2::Regexp} used in the match.
112
106
  *
107
+ * @return [RE2::Regexp] the regexp used in the match
108
+ * @example
113
109
  * m = RE2('(\d+)').match("bob 123")
114
110
  * m.regexp #=> #<RE2::Regexp /(\d+)/>
115
111
  */
@@ -129,11 +125,10 @@ extern "C" {
129
125
  }
130
126
 
131
127
  /*
132
- * call-seq:
133
- * match.to_a -> array
134
- *
135
128
  * Returns the array of matches.
136
129
  *
130
+ * @return [Array<String, nil>] the array of matches
131
+ * @example
137
132
  * m = RE2('(\d+)').match("bob 123")
138
133
  * m.to_a #=> ["123", "123"]
139
134
  */
@@ -168,18 +163,37 @@ extern "C" {
168
163
  }
169
164
 
170
165
  /*
171
- * call-seq:
172
- * match[i] -> string
173
- * match[start, length] -> array
174
- * match[range] -> array
166
+ * Retrieve zero, one or more matches by index.
175
167
  *
176
- * Access the match data as an array.
168
+ * @return [Array<String, nil>, String, Boolean]
177
169
  *
178
- * m = RE2('(\d+)').match("bob 123")
179
- * m[0] #=> "123"
180
- * m[0, 1] #=> ["123"]
181
- * m[0...1] #=> ["123"]
182
- * m[0..1] #=> ["123", "123"]
170
+ * @overload [](index)
171
+ * Access a particular match by index.
172
+ *
173
+ * @param [Fixnum] index the index of the match to fetch
174
+ * @return [String, nil] the specified match
175
+ * @example
176
+ * m = RE2('(\d+)').match("bob 123")
177
+ * m[0] #=> "123"
178
+ *
179
+ * @overload [](start, length)
180
+ * Access a range of matches by starting index and length.
181
+ *
182
+ * @param [Fixnum] start the index from which to start
183
+ * @param [Fixnum] length the number of elements to fetch
184
+ * @return [Array<String, nil>] the specified matches
185
+ * @example
186
+ * m = RE2('(\d+)').match("bob 123")
187
+ * m[0, 1] #=> ["123"]
188
+ *
189
+ * @overload [](range)
190
+ * Access a range of matches by index.
191
+ *
192
+ * @param [Range] range the range of match indexes to fetch
193
+ * @return [Array<String, nil>] the specified matches
194
+ * @example
195
+ * m = RE2('(\d+)').match("bob 123")
196
+ * m[0..1] #=> "[123", "123"]
183
197
  */
184
198
  static VALUE
185
199
  re2_matchdata_aref(int argc, VALUE *argv, VALUE self)
@@ -195,10 +209,9 @@ extern "C" {
195
209
  }
196
210
 
197
211
  /*
198
- * call-seq:
199
- * match.to_s -> string
200
- *
201
212
  * Returns the entire matched string.
213
+ *
214
+ * @return [String] the entire matched string
202
215
  */
203
216
  static VALUE
204
217
  re2_matchdata_to_s(VALUE self)
@@ -207,11 +220,10 @@ extern "C" {
207
220
  }
208
221
 
209
222
  /*
210
- * call-seq:
211
- * match.inspect -> string
212
- *
213
223
  * Returns a printable version of the match.
214
224
  *
225
+ * @return [String] a printable version of the match
226
+ * @example
215
227
  * m = RE2('(\d+)').match("bob 123")
216
228
  * m.inspect #=> "#<RE2::MatchData \"123\" 1:\"123\">"
217
229
  */
@@ -224,38 +236,40 @@ extern "C" {
224
236
 
225
237
  Data_Get_Struct(self, re2_matchdata, m);
226
238
 
227
- result = rb_str_buf_new2("#<RE2::MatchData");
239
+ result = rb_str_new2("#<RE2::MatchData");
228
240
 
229
241
  for (i = 0; i < m->number_of_matches; i++) {
230
- rb_str_buf_cat2(result, " ");
242
+ rb_str_cat2(result, " ");
231
243
 
232
244
  if (i > 0) {
233
245
  char buf[sizeof(i)*3+1];
234
246
  snprintf(buf, sizeof(buf), "%d", i);
235
- rb_str_buf_cat2(result, buf);
236
- rb_str_buf_cat2(result, ":");
247
+ rb_str_cat2(result, buf);
248
+ rb_str_cat2(result, ":");
237
249
  }
238
250
 
239
251
  match = re2_matchdata_nth_match(i, self);
240
252
 
241
253
  if (match == Qnil) {
242
- rb_str_buf_cat2(result, "nil");
254
+ rb_str_cat2(result, "nil");
243
255
  } else {
244
- rb_str_buf_append(result, rb_str_inspect(match));
256
+ rb_str_append(result, rb_str_inspect(match));
245
257
  }
246
258
  }
247
- rb_str_buf_cat2(result, ">");
259
+ rb_str_cat2(result, ">");
248
260
 
249
261
  return result;
250
262
  }
251
263
 
252
264
  /*
253
- * call-seq:
254
- * RE2(pattern) -> re2
255
- * RE2(pattern, options) -> re2
256
- *
257
265
  * Returns a new RE2 object with a compiled version of
258
266
  * +pattern+ stored inside. Equivalent to +RE2.new+.
267
+ *
268
+ * @return [RE2::Regexp] an RE2::Regexp with the specified pattern and options
269
+ * @param [String] pattern the pattern to compile
270
+ * @param [Hash] options the options to compile a regexp with
271
+ * @see RE2::Regexp.new
272
+ *
259
273
  */
260
274
  static VALUE
261
275
  re2_re2(int argc, VALUE *argv, VALUE self)
@@ -265,49 +279,38 @@ extern "C" {
265
279
  }
266
280
 
267
281
  /*
268
- * call-seq:
269
- * RE2::Regexp.new(pattern) -> re2
270
- * RE2::Regexp.new(pattern, options) -> re2
271
- * RE2::Regexp.compile(pattern) -> re2
272
- * RE2::Regexp.compile(pattern, options) -> re2
273
- *
274
- * Returns a new RE2 object with a compiled version of
282
+ * Returns a new {RE2::Regexp} object with a compiled version of
275
283
  * +pattern+ stored inside.
276
284
  *
277
- * Options can be a hash with the following keys:
278
- *
279
- * :utf8 - text and pattern are UTF-8; otherwise
280
- * Latin-1 (default true)
281
- *
282
- * :posix_syntax - restrict regexps to POSIX egrep syntax
283
- * (default false)
284
- *
285
- * :longest_match - search for longest match, not first match
286
- * (default false)
287
- *
288
- * :log_errors - log syntax and execution errors to ERROR
289
- * (default true)
290
- *
291
- * :max_mem - approx. max memory footprint of RE2
292
- *
293
- * :literal - interpret string as literal, not regexp
294
- * (default false)
295
- *
296
- * :never_nl - never match \n, even if it is in regexp
297
- * (default false)
298
- *
299
- * :case_sensitive - match is case-sensitive (regexp can override
300
- * with (?i) unless in posix_syntax mode)
301
- * (default true)
302
- *
303
- * :perl_classes - allow Perl's \d \s \w \D \S \W when in
304
- * posix_syntax mode (default false)
305
- *
306
- * :word_boundary - allow \b \B (word boundary and not) when
307
- * in posix_syntax mode (default false)
308
- *
309
- * :one_line - ^ and $ only match beginning and end of text
310
- * when in posix_syntax mode (default false)
285
+ * @return [RE2::Regexp]
286
+ *
287
+ * @overload initialize(pattern)
288
+ * Returns a new {RE2::Regexp} object with a compiled version of
289
+ * +pattern+ stored inside with the default options.
290
+ *
291
+ * @param [String] pattern the pattern to compile
292
+ * @return [RE2::Regexp] an RE2::Regexp with the specified pattern
293
+ * @raise [NoMemoryError] if memory could not be allocated for the compiled pattern
294
+ *
295
+ * @overload initialize(pattern, options)
296
+ * Returns a new {RE2::Regexp} object with a compiled version of
297
+ * +pattern+ stored inside with the specified options.
298
+ *
299
+ * @param [String] pattern the pattern to compile
300
+ * @param [Hash] options the options with which to compile the pattern
301
+ * @option options [Boolean] :utf8 (true) text and pattern are UTF-8; otherwise Latin-1
302
+ * @option options [Boolean] :posix_syntax (false) restrict regexps to POSIX egrep syntax
303
+ * @option options [Boolean] :longest_match (false) search for longest match, not first match
304
+ * @option options [Boolean] :log_errors (true) log syntax and execution errors to ERROR
305
+ * @option options [Fixnum] :max_mem approx. max memory footprint of RE2
306
+ * @option options [Boolean] :literal (false) interpret string as literal, not regexp
307
+ * @option options [Boolean] :never_nl (false) never match \n, even if it is in regexp
308
+ * @option options [Boolean] :case_sensitive (true) match is case-sensitive (regexp can override with (?i) unless in posix_syntax mode)
309
+ * @option options [Boolean] :perl_classes (false) allow Perl's \d \s \w \D \S \W when in posix_syntax mode
310
+ * @option options [Boolean] :word_boundary (false) allow \b \B (word boundary and not) when in posix_syntax mode
311
+ * @option options [Boolean] :one_line (false) ^ and $ only match beginning and end of text when in posix_syntax mode
312
+ * @return [RE2::Regexp] an RE2::Regexp with the specified pattern and options
313
+ * @raise [NoMemoryError] if memory could not be allocated for the compiled pattern
311
314
  */
312
315
  static VALUE
313
316
  re2_regexp_initialize(int argc, VALUE *argv, VALUE self)
@@ -395,11 +398,10 @@ extern "C" {
395
398
  }
396
399
 
397
400
  /*
398
- * call-seq:
399
- * re2.inspect -> string
400
- *
401
401
  * Returns a printable version of the regular expression +re2+.
402
402
  *
403
+ * @return [String] a printable version of the regular expression
404
+ * @example
403
405
  * re2 = RE2::Regexp.new("woo?")
404
406
  * re2.inspect #=> "#<RE2::Regexp /woo?/>"
405
407
  */
@@ -407,25 +409,20 @@ extern "C" {
407
409
  re2_regexp_inspect(VALUE self)
408
410
  {
409
411
  re2_pattern *p;
410
- VALUE result = rb_str_buf_new2("#<RE2::Regexp /");
412
+ VALUE result = rb_str_new2("#<RE2::Regexp /");
411
413
 
412
414
  Data_Get_Struct(self, re2_pattern, p);
413
- rb_str_buf_cat2(result, p->pattern->pattern().c_str());
414
- rb_str_buf_cat2(result, "/>");
415
+ rb_str_cat2(result, p->pattern->pattern().c_str());
416
+ rb_str_cat2(result, "/>");
415
417
 
416
418
  return result;
417
419
  }
418
420
 
419
421
  /*
420
- * call-seq:
421
- * re2.to_s -> string
422
- * re2.to_str -> string
423
- * re2.pattern -> string
424
- * re2.source -> string
425
- * re2.inspect -> string
426
- *
427
422
  * Returns a string version of the regular expression +re2+.
428
423
  *
424
+ * @return [String] a string version of the regular expression
425
+ * @example
429
426
  * re2 = RE2::Regexp.new("woo?")
430
427
  * re2.to_s #=> "woo?"
431
428
  */
@@ -438,12 +435,11 @@ extern "C" {
438
435
  }
439
436
 
440
437
  /*
441
- * call-seq:
442
- * re2.ok? -> true or false
443
- *
444
438
  * Returns whether or not the regular expression +re2+
445
439
  * was compiled successfully or not.
446
440
  *
441
+ * @return [Boolean] whether or not compilation was successful
442
+ * @example
447
443
  * re2 = RE2::Regexp.new("woo?")
448
444
  * re2.ok? #=> true
449
445
  */
@@ -456,12 +452,11 @@ extern "C" {
456
452
  }
457
453
 
458
454
  /*
459
- * call-seq:
460
- * re2.utf8? -> true or false
461
- *
462
455
  * Returns whether or not the regular expression +re2+
463
456
  * was compiled with the utf8 option set to true.
464
457
  *
458
+ * @return [Boolean] the utf8 option
459
+ * @example
465
460
  * re2 = RE2::Regexp.new("woo?", :utf8 => true)
466
461
  * re2.utf8? #=> true
467
462
  */
@@ -474,12 +469,11 @@ extern "C" {
474
469
  }
475
470
 
476
471
  /*
477
- * call-seq:
478
- * re2.posix_syntax? -> true or false
479
- *
480
472
  * Returns whether or not the regular expression +re2+
481
473
  * was compiled with the posix_syntax option set to true.
482
474
  *
475
+ * @return [Boolean] the posix_syntax option
476
+ * @example
483
477
  * re2 = RE2::Regexp.new("woo?", :posix_syntax => true)
484
478
  * re2.posix_syntax? #=> true
485
479
  */
@@ -492,12 +486,11 @@ extern "C" {
492
486
  }
493
487
 
494
488
  /*
495
- * call-seq:
496
- * re2.longest_match? -> true or false
497
- *
498
489
  * Returns whether or not the regular expression +re2+
499
490
  * was compiled with the longest_match option set to true.
500
491
  *
492
+ * @return [Boolean] the longest_match option
493
+ * @example
501
494
  * re2 = RE2::Regexp.new("woo?", :longest_match => true)
502
495
  * re2.longest_match? #=> true
503
496
  */
@@ -510,12 +503,11 @@ extern "C" {
510
503
  }
511
504
 
512
505
  /*
513
- * call-seq:
514
- * re2.log_errors? -> true or false
515
- *
516
506
  * Returns whether or not the regular expression +re2+
517
507
  * was compiled with the log_errors option set to true.
518
508
  *
509
+ * @return [Boolean] the log_errors option
510
+ * @example
519
511
  * re2 = RE2::Regexp.new("woo?", :log_errors => true)
520
512
  * re2.log_errors? #=> true
521
513
  */
@@ -528,12 +520,11 @@ extern "C" {
528
520
  }
529
521
 
530
522
  /*
531
- * call-seq:
532
- * re2.max_mem -> int
533
- *
534
523
  * Returns the max_mem setting for the regular expression
535
524
  * +re2+.
536
525
  *
526
+ * @return [Fixnum] the max_mem option
527
+ * @example
537
528
  * re2 = RE2::Regexp.new("woo?", :max_mem => 1024)
538
529
  * re2.max_mem #=> 1024
539
530
  */
@@ -546,12 +537,11 @@ extern "C" {
546
537
  }
547
538
 
548
539
  /*
549
- * call-seq:
550
- * re2.literal? -> true or false
551
- *
552
540
  * Returns whether or not the regular expression +re2+
553
541
  * was compiled with the literal option set to true.
554
542
  *
543
+ * @return [Boolean] the literal option
544
+ * @example
555
545
  * re2 = RE2::Regexp.new("woo?", :literal => true)
556
546
  * re2.literal? #=> true
557
547
  */
@@ -564,12 +554,11 @@ extern "C" {
564
554
  }
565
555
 
566
556
  /*
567
- * call-seq:
568
- * re2.never_nl? -> true or false
569
- *
570
557
  * Returns whether or not the regular expression +re2+
571
558
  * was compiled with the never_nl option set to true.
572
559
  *
560
+ * @return [Boolean] the never_nl option
561
+ * @example
573
562
  * re2 = RE2::Regexp.new("woo?", :never_nl => true)
574
563
  * re2.never_nl? #=> true
575
564
  */
@@ -582,12 +571,11 @@ extern "C" {
582
571
  }
583
572
 
584
573
  /*
585
- * call-seq:
586
- * re2.case_sensitive? -> true or false
587
- *
588
574
  * Returns whether or not the regular expression +re2+
589
575
  * was compiled with the case_sensitive option set to true.
590
576
  *
577
+ * @return [Boolean] the case_sensitive option
578
+ * @example
591
579
  * re2 = RE2::Regexp.new("woo?", :case_sensitive => true)
592
580
  * re2.case_sensitive? #=> true
593
581
  */
@@ -600,15 +588,14 @@ extern "C" {
600
588
  }
601
589
 
602
590
  /*
603
- * call-seq:
604
- * re2.case_insensitive? -> true or false
605
- * re2.casefold? -> true or false
606
- *
607
591
  * Returns whether or not the regular expression +re2+
608
592
  * was compiled with the case_sensitive option set to false.
609
593
  *
594
+ * @return [Boolean] the inverse of the case_sensitive option
595
+ * @example
610
596
  * re2 = RE2::Regexp.new("woo?", :case_sensitive => true)
611
597
  * re2.case_insensitive? #=> false
598
+ * re2.casefold? #=> false
612
599
  */
613
600
  static VALUE
614
601
  re2_regexp_case_insensitive(VALUE self)
@@ -617,12 +604,11 @@ extern "C" {
617
604
  }
618
605
 
619
606
  /*
620
- * call-seq:
621
- * re2.perl_classes? -> true or false
622
- *
623
607
  * Returns whether or not the regular expression +re2+
624
608
  * was compiled with the perl_classes option set to true.
625
609
  *
610
+ * @return [Boolean] the perl_classes option
611
+ * @example
626
612
  * re2 = RE2::Regexp.new("woo?", :perl_classes => true)
627
613
  * re2.perl_classes? #=> true
628
614
  */
@@ -635,12 +621,11 @@ extern "C" {
635
621
  }
636
622
 
637
623
  /*
638
- * call-seq:
639
- * re2.word_boundary? -> true or false
640
- *
641
624
  * Returns whether or not the regular expression +re2+
642
625
  * was compiled with the word_boundary option set to true.
643
626
  *
627
+ * @return [Boolean] the word_boundary option
628
+ * @example
644
629
  * re2 = RE2::Regexp.new("woo?", :word_boundary => true)
645
630
  * re2.word_boundary? #=> true
646
631
  */
@@ -653,12 +638,11 @@ extern "C" {
653
638
  }
654
639
 
655
640
  /*
656
- * call-seq:
657
- * re2.one_line? -> true or false
658
- *
659
641
  * Returns whether or not the regular expression +re2+
660
642
  * was compiled with the one_line option set to true.
661
643
  *
644
+ * @return [Boolean] the one_line option
645
+ * @example
662
646
  * re2 = RE2::Regexp.new("woo?", :one_line => true)
663
647
  * re2.one_line? #=> true
664
648
  */
@@ -671,11 +655,10 @@ extern "C" {
671
655
  }
672
656
 
673
657
  /*
674
- * call-seq:
675
- * re2.error -> error_str
676
- *
677
658
  * If the RE2 could not be created properly, returns an
678
659
  * error string.
660
+ *
661
+ * @return [String] the error string
679
662
  */
680
663
  static VALUE
681
664
  re2_regexp_error(VALUE self)
@@ -686,11 +669,10 @@ extern "C" {
686
669
  }
687
670
 
688
671
  /*
689
- * call-seq:
690
- * re2.error_arg -> error_str
691
- *
692
672
  * If the RE2 could not be created properly, returns
693
673
  * the offending portion of the regexp.
674
+ *
675
+ * @return [String] the offending portion of the regexp
694
676
  */
695
677
  static VALUE
696
678
  re2_regexp_error_arg(VALUE self)
@@ -701,12 +683,11 @@ extern "C" {
701
683
  }
702
684
 
703
685
  /*
704
- * call-seq:
705
- * re2.program_size -> size
706
- *
707
686
  * Returns the program size, a very approximate measure
708
687
  * of a regexp's "cost". Larger numbers are more expensive
709
688
  * than smaller numbers.
689
+ *
690
+ * @return [Fixnum] the regexp "cost"
710
691
  */
711
692
  static VALUE
712
693
  re2_regexp_program_size(VALUE self)
@@ -717,11 +698,10 @@ extern "C" {
717
698
  }
718
699
 
719
700
  /*
720
- * call-seq:
721
- * re2.options -> options_hash
722
- *
723
701
  * Returns a hash of the options currently set for
724
702
  * +re2+.
703
+ *
704
+ * @return [Hash] the options
725
705
  */
726
706
  static VALUE
727
707
  re2_regexp_options(VALUE self)
@@ -765,19 +745,18 @@ extern "C" {
765
745
  rb_hash_aset(options, ID2SYM(id_one_line),
766
746
  BOOL2RUBY(p->pattern->options().one_line()));
767
747
 
768
- // This is a read-only hash after all...
748
+ /* This is a read-only hash after all... */
769
749
  OBJ_FREEZE(options);
770
750
 
771
751
  return options;
772
752
  }
773
753
 
774
754
  /*
775
- * call-seq:
776
- * re2.number_of_capturing_groups -> int
777
- *
778
755
  * Returns the number of capturing subpatterns, or -1 if the regexp
779
756
  * wasn't valid on construction. The overall match ($0) does not
780
757
  * count: if the regexp is "(a)(b)", returns 2.
758
+ *
759
+ * @return [Fixnum] the number of capturing subpatterns
781
760
  */
782
761
  static VALUE
783
762
  re2_regexp_number_of_capturing_groups(VALUE self)
@@ -789,24 +768,48 @@ extern "C" {
789
768
  }
790
769
 
791
770
  /*
792
- * call-seq:
793
- * re2.match(text) -> [match, match]
794
- * re2.match(text, 0) -> true or false
795
- * re2.match(text, num_of_matches) -> [match, match]
796
- *
797
- * Looks for the pattern in +re2+ in +text+; when specified
798
- * without a second argument, will return an array of the matching
799
- * pattern and all subpatterns. If the second argument is 0, a
800
- * simple true or false will be returned to indicate a successful
801
- * match. If the second argument is any integer greater than 0,
802
- * that number of matches will be returned (padded with nils if
803
- * there are insufficient matches).
804
- *
805
- * r = RE2::Regexp.new('w(o)(o)')
806
- * r.match('woo') #=> ["woo", "o", "o"]
807
- * r.match('woo', 0) #=> true
808
- * r.match('bob', 0) #=> false
809
- * r.match('woo', 1) #=> ["woo", "o"]
771
+ * Match the pattern against the given +text+ and return either
772
+ * a boolean (if no submatches are required) or a {RE2::MatchData}
773
+ * instance.
774
+ *
775
+ * @return [Boolean, RE2::MatchData]
776
+ *
777
+ * @overload match(text)
778
+ * Returns an {RE2::MatchData} containing the matching
779
+ * pattern and all subpatterns resulting from looking for
780
+ * the regexp in +text+.
781
+ *
782
+ * @param [String] text the text to search
783
+ * @return [RE2::MatchData] the matches
784
+ * @raise [NoMemoryError] if there was not enough memory to allocate the matches
785
+ * @example
786
+ * r = RE2::Regexp.new('w(o)(o)')
787
+ * r.match('woo) #=> #<RE2::MatchData "woo" 1:"o" 2:"o">
788
+ *
789
+ * @overload match(text, 0)
790
+ * Returns either true or false indicating whether a
791
+ * successful match was made.
792
+ *
793
+ * @param [String] text the text to search
794
+ * @return [Boolean] whether the match was successful
795
+ * @raise [NoMemoryError] if there was not enough memory to allocate the matches
796
+ * @example
797
+ * r = RE2::Regexp.new('w(o)(o)')
798
+ * r.match('woo', 0) #=> true
799
+ * r.match('bob', 0) #=> false
800
+ *
801
+ * @overload match(text, number_of_matches)
802
+ * See +match(text)+ but with a specific number of
803
+ * matches returned (padded with nils if necessary).
804
+ *
805
+ * @param [String] text the text to search
806
+ * @param [Fixnum] number_of_matches the number of matches to return
807
+ * @return [RE2::MatchData] the matches
808
+ * @raise [NoMemoryError] if there was not enough memory to allocate the matches
809
+ * @example
810
+ * r = RE2::Regexp.new('w(o)(o)')
811
+ * r.match('woo', 1) #=> #<RE2::MatchData "woo" 1:"o">
812
+ * r.match('woo', 3) #=> #<RE2::MatchData "woo" 1:"o" 2:"o" 3:nil>
810
813
  */
811
814
  static VALUE
812
815
  re2_regexp_match(int argc, VALUE *argv, VALUE self)
@@ -860,12 +863,10 @@ extern "C" {
860
863
  }
861
864
 
862
865
  /*
863
- * call-seq:
864
- * re2.match?(text) -> true or false
865
- * re2 =~ text -> true or false
866
- *
867
866
  * Returns true or false to indicate a successful match.
868
867
  * Equivalent to +re2.match(text, 0)+.
868
+ *
869
+ * @return [Boolean] whether the match was successful
869
870
  */
870
871
  static VALUE
871
872
  re2_regexp_match_query(VALUE self, VALUE text)
@@ -878,12 +879,13 @@ extern "C" {
878
879
  }
879
880
 
880
881
  /*
881
- * call-seq:
882
- * RE2::Replace(str, pattern, rewrite) -> str
883
- *
884
882
  * Replaces the first occurrence +pattern+ in +str+ with
885
883
  * +rewrite+ <i>in place</i>.
886
884
  *
885
+ * @param [String] str the string to modify
886
+ * @param [String, RE2::Regexp] pattern a regexp matching text to be replaced
887
+ * @param [String] rewrite the string to replace with
888
+ * @example
887
889
  * RE2::Replace("hello there", "hello", "howdy") #=> "howdy there"
888
890
  * re2 = RE2.new("hel+o")
889
891
  * RE2::Replace("hello there", re2, "yo") #=> "yo there"
@@ -898,11 +900,11 @@ extern "C" {
898
900
  VALUE repl;
899
901
  re2_pattern *p;
900
902
 
901
- // Convert all the inputs to be pumped into RE2::Replace.
903
+ /* Convert all the inputs to be pumped into RE2::Replace. */
902
904
  std::string str_as_string(StringValuePtr(str));
903
905
  re2::StringPiece rewrite_as_string_piece(StringValuePtr(rewrite));
904
906
 
905
- // Do the replacement.
907
+ /* Do the replacement. */
906
908
  if (rb_obj_is_kind_of(pattern, re2_cRegexp)) {
907
909
  Data_Get_Struct(pattern, re2_pattern, p);
908
910
  RE2::Replace(&str_as_string, *p->pattern, rewrite_as_string_piece);
@@ -910,22 +912,23 @@ extern "C" {
910
912
  RE2::Replace(&str_as_string, StringValuePtr(pattern), rewrite_as_string_piece);
911
913
  }
912
914
 
913
- // Save the replacement as a VALUE.
915
+ /* Save the replacement as a VALUE. */
914
916
  repl = rb_str_new(str_as_string.c_str(), str_as_string.length());
915
917
 
916
- // Replace the original string with the replacement.
918
+ /* Replace the original string with the replacement. */
917
919
  rb_str_update(str, 0, RSTRING_LEN(str), repl);
918
920
 
919
921
  return str;
920
922
  }
921
923
 
922
924
  /*
923
- * call-seq:
924
- * RE2::GlobalReplace(str, pattern, rewrite) -> str
925
- *
926
925
  * Replaces every occurrence of +pattern+ in +str+ with
927
926
  * +rewrite+ <i>in place</i>.
928
927
  *
928
+ * @param [String] str the string to modify
929
+ * @param [String, RE2::Regexp] pattern a regexp matching text to be replaced
930
+ * @param [String] rewrite the string to replace with
931
+ * @example
929
932
  * RE2::GlobalReplace("hello there", "e", "i") #=> "hillo thiri"
930
933
  * re2 = RE2.new("oo?")
931
934
  * RE2::GlobalReplace("whoops-doops", re2, "e") #=> "wheps-deps"
@@ -938,13 +941,13 @@ extern "C" {
938
941
  {
939
942
  UNUSED(self);
940
943
 
941
- // Convert all the inputs to be pumped into RE2::GlobalReplace.
944
+ /* Convert all the inputs to be pumped into RE2::GlobalReplace. */
942
945
  re2_pattern *p;
943
946
  std::string str_as_string(StringValuePtr(str));
944
947
  re2::StringPiece rewrite_as_string_piece(StringValuePtr(rewrite));
945
948
  VALUE repl;
946
949
 
947
- // Do the replacement.
950
+ /* Do the replacement. */
948
951
  if (rb_obj_is_kind_of(pattern, re2_cRegexp)) {
949
952
  Data_Get_Struct(pattern, re2_pattern, p);
950
953
  RE2::GlobalReplace(&str_as_string, *p->pattern, rewrite_as_string_piece);
@@ -952,26 +955,24 @@ extern "C" {
952
955
  RE2::GlobalReplace(&str_as_string, StringValuePtr(pattern), rewrite_as_string_piece);
953
956
  }
954
957
 
955
- // Save the replacement as a VALUE.
958
+ /* Save the replacement as a VALUE. */
956
959
  repl = rb_str_new(str_as_string.c_str(), str_as_string.length());
957
960
 
958
- // Replace the original string with the replacement.
961
+ /* Replace the original string with the replacement. */
959
962
  rb_str_update(str, 0, RSTRING_LEN(str), repl);
960
963
 
961
964
  return str;
962
965
  }
963
966
 
964
967
  /*
965
- * call-seq:
966
- * RE2::QuoteMeta(str) -> str
967
- * RE2::Regexp.escape(str) -> str
968
- * RE2::Regexp.quote(str) -> str
969
- *
970
968
  * Returns a version of str with all potentially meaningful regexp
971
969
  * characters escaped. The returned string, used as a regular
972
970
  * expression, will exactly match the original string.
973
971
  *
974
- * RE2::QuoteMeta("1.5-2.0?") #=> "1\.5\-2\.0\?"
972
+ * @param [String] unquoted the unquoted string
973
+ * @return [String] the escaped string
974
+ * @example
975
+ * RE2::Regexp.escape("1.5-2.0?") #=> "1\.5\-2\.0\?"
975
976
  */
976
977
  static VALUE
977
978
  re2_QuoteMeta(VALUE self, VALUE unquoted)
@@ -991,53 +992,53 @@ extern "C" {
991
992
  rb_define_alloc_func(re2_cRegexp, (VALUE (*)(VALUE))re2_regexp_allocate);
992
993
  rb_define_alloc_func(re2_cMatchData, (VALUE (*)(VALUE))re2_matchdata_allocate);
993
994
 
994
- rb_define_method(re2_cMatchData, "string", (VALUE (*)(...))re2_matchdata_string, 0);
995
- rb_define_method(re2_cMatchData, "regexp", (VALUE (*)(...))re2_matchdata_regexp, 0);
996
- rb_define_method(re2_cMatchData, "to_a", (VALUE (*)(...))re2_matchdata_to_a, 0);
997
- rb_define_method(re2_cMatchData, "size", (VALUE (*)(...))re2_matchdata_size, 0);
998
- rb_define_method(re2_cMatchData, "length", (VALUE (*)(...))re2_matchdata_size, 0);
999
- rb_define_method(re2_cMatchData, "[]", (VALUE (*)(...))re2_matchdata_aref, -1);
1000
- rb_define_method(re2_cMatchData, "to_s", (VALUE (*)(...))re2_matchdata_to_s, 0);
1001
- rb_define_method(re2_cMatchData, "inspect", (VALUE (*)(...))re2_matchdata_inspect, 0);
1002
-
1003
- rb_define_method(re2_cRegexp, "initialize", (VALUE (*)(...))re2_regexp_initialize, -1);
1004
- rb_define_method(re2_cRegexp, "ok?", (VALUE (*)(...))re2_regexp_ok, 0);
1005
- rb_define_method(re2_cRegexp, "error", (VALUE (*)(...))re2_regexp_error, 0);
1006
- rb_define_method(re2_cRegexp, "error_arg", (VALUE (*)(...))re2_regexp_error_arg, 0);
1007
- rb_define_method(re2_cRegexp, "program_size", (VALUE (*)(...))re2_regexp_program_size, 0);
1008
- rb_define_method(re2_cRegexp, "options", (VALUE (*)(...))re2_regexp_options, 0);
1009
- rb_define_method(re2_cRegexp, "number_of_capturing_groups", (VALUE (*)(...))re2_regexp_number_of_capturing_groups, 0);
1010
- rb_define_method(re2_cRegexp, "match", (VALUE (*)(...))re2_regexp_match, -1);
1011
- rb_define_method(re2_cRegexp, "match?", (VALUE (*)(...))re2_regexp_match_query, 1);
1012
- rb_define_method(re2_cRegexp, "=~", (VALUE (*)(...))re2_regexp_match_query, 1);
1013
- rb_define_method(re2_cRegexp, "===", (VALUE (*)(...))re2_regexp_match_query, 1);
1014
- rb_define_method(re2_cRegexp, "to_s", (VALUE (*)(...))re2_regexp_to_s, 0);
1015
- rb_define_method(re2_cRegexp, "to_str", (VALUE (*)(...))re2_regexp_to_s, 0);
1016
- rb_define_method(re2_cRegexp, "pattern", (VALUE (*)(...))re2_regexp_to_s, 0);
1017
- rb_define_method(re2_cRegexp, "source", (VALUE (*)(...))re2_regexp_to_s, 0);
1018
- rb_define_method(re2_cRegexp, "inspect", (VALUE (*)(...))re2_regexp_inspect, 0);
1019
- rb_define_method(re2_cRegexp, "utf8?", (VALUE (*)(...))re2_regexp_utf8, 0);
1020
- rb_define_method(re2_cRegexp, "posix_syntax?", (VALUE (*)(...))re2_regexp_posix_syntax, 0);
1021
- rb_define_method(re2_cRegexp, "longest_match?", (VALUE (*)(...))re2_regexp_longest_match, 0);
1022
- rb_define_method(re2_cRegexp, "log_errors?", (VALUE (*)(...))re2_regexp_log_errors, 0);
1023
- rb_define_method(re2_cRegexp, "max_mem", (VALUE (*)(...))re2_regexp_max_mem, 0);
1024
- rb_define_method(re2_cRegexp, "literal?", (VALUE (*)(...))re2_regexp_literal, 0);
1025
- rb_define_method(re2_cRegexp, "never_nl?", (VALUE (*)(...))re2_regexp_never_nl, 0);
1026
- rb_define_method(re2_cRegexp, "case_sensitive?", (VALUE (*)(...))re2_regexp_case_sensitive, 0);
1027
- rb_define_method(re2_cRegexp, "case_insensitive?", (VALUE (*)(...))re2_regexp_case_insensitive, 0);
1028
- rb_define_method(re2_cRegexp, "casefold?", (VALUE (*)(...))re2_regexp_case_insensitive, 0);
1029
- rb_define_method(re2_cRegexp, "perl_classes?", (VALUE (*)(...))re2_regexp_perl_classes, 0);
1030
- rb_define_method(re2_cRegexp, "word_boundary?", (VALUE (*)(...))re2_regexp_word_boundary, 0);
1031
- rb_define_method(re2_cRegexp, "one_line?", (VALUE (*)(...))re2_regexp_one_line, 0);
1032
-
1033
- rb_define_module_function(re2_mRE2, "Replace", (VALUE (*)(...))re2_Replace, 3);
1034
- rb_define_module_function(re2_mRE2, "GlobalReplace", (VALUE (*)(...))re2_GlobalReplace, 3);
1035
- rb_define_module_function(re2_mRE2, "QuoteMeta", (VALUE (*)(...))re2_QuoteMeta, 1);
1036
- rb_define_singleton_method(re2_cRegexp, "escape", (VALUE (*)(...))re2_QuoteMeta, 1);
1037
- rb_define_singleton_method(re2_cRegexp, "quote", (VALUE (*)(...))re2_QuoteMeta, 1);
1038
- rb_define_singleton_method(re2_cRegexp, "compile", (VALUE (*)(...))rb_class_new_instance, -1);
1039
-
1040
- rb_define_global_function("RE2", (VALUE (*)(...))re2_re2, -1);
995
+ rb_define_method(re2_cMatchData, "string", RUBY_METHOD_FUNC(re2_matchdata_string), 0);
996
+ rb_define_method(re2_cMatchData, "regexp", RUBY_METHOD_FUNC(re2_matchdata_regexp), 0);
997
+ rb_define_method(re2_cMatchData, "to_a", RUBY_METHOD_FUNC(re2_matchdata_to_a), 0);
998
+ rb_define_method(re2_cMatchData, "size", RUBY_METHOD_FUNC(re2_matchdata_size), 0);
999
+ rb_define_method(re2_cMatchData, "length", RUBY_METHOD_FUNC(re2_matchdata_size), 0);
1000
+ rb_define_method(re2_cMatchData, "[]", RUBY_METHOD_FUNC(re2_matchdata_aref), -1);
1001
+ rb_define_method(re2_cMatchData, "to_s", RUBY_METHOD_FUNC(re2_matchdata_to_s), 0);
1002
+ rb_define_method(re2_cMatchData, "inspect", RUBY_METHOD_FUNC(re2_matchdata_inspect), 0);
1003
+
1004
+ rb_define_method(re2_cRegexp, "initialize", RUBY_METHOD_FUNC(re2_regexp_initialize), -1);
1005
+ rb_define_method(re2_cRegexp, "ok?", RUBY_METHOD_FUNC(re2_regexp_ok), 0);
1006
+ rb_define_method(re2_cRegexp, "error", RUBY_METHOD_FUNC(re2_regexp_error), 0);
1007
+ rb_define_method(re2_cRegexp, "error_arg", RUBY_METHOD_FUNC(re2_regexp_error_arg), 0);
1008
+ rb_define_method(re2_cRegexp, "program_size", RUBY_METHOD_FUNC(re2_regexp_program_size), 0);
1009
+ rb_define_method(re2_cRegexp, "options", RUBY_METHOD_FUNC(re2_regexp_options), 0);
1010
+ rb_define_method(re2_cRegexp, "number_of_capturing_groups", RUBY_METHOD_FUNC(re2_regexp_number_of_capturing_groups), 0);
1011
+ rb_define_method(re2_cRegexp, "match", RUBY_METHOD_FUNC(re2_regexp_match), -1);
1012
+ rb_define_method(re2_cRegexp, "match?", RUBY_METHOD_FUNC(re2_regexp_match_query), 1);
1013
+ rb_define_method(re2_cRegexp, "=~", RUBY_METHOD_FUNC(re2_regexp_match_query), 1);
1014
+ rb_define_method(re2_cRegexp, "===", RUBY_METHOD_FUNC(re2_regexp_match_query), 1);
1015
+ rb_define_method(re2_cRegexp, "to_s", RUBY_METHOD_FUNC(re2_regexp_to_s), 0);
1016
+ rb_define_method(re2_cRegexp, "to_str", RUBY_METHOD_FUNC(re2_regexp_to_s), 0);
1017
+ rb_define_method(re2_cRegexp, "pattern", RUBY_METHOD_FUNC(re2_regexp_to_s), 0);
1018
+ rb_define_method(re2_cRegexp, "source", RUBY_METHOD_FUNC(re2_regexp_to_s), 0);
1019
+ rb_define_method(re2_cRegexp, "inspect", RUBY_METHOD_FUNC(re2_regexp_inspect), 0);
1020
+ rb_define_method(re2_cRegexp, "utf8?", RUBY_METHOD_FUNC(re2_regexp_utf8), 0);
1021
+ rb_define_method(re2_cRegexp, "posix_syntax?", RUBY_METHOD_FUNC(re2_regexp_posix_syntax), 0);
1022
+ rb_define_method(re2_cRegexp, "longest_match?", RUBY_METHOD_FUNC(re2_regexp_longest_match), 0);
1023
+ rb_define_method(re2_cRegexp, "log_errors?", RUBY_METHOD_FUNC(re2_regexp_log_errors), 0);
1024
+ rb_define_method(re2_cRegexp, "max_mem", RUBY_METHOD_FUNC(re2_regexp_max_mem), 0);
1025
+ rb_define_method(re2_cRegexp, "literal?", RUBY_METHOD_FUNC(re2_regexp_literal), 0);
1026
+ rb_define_method(re2_cRegexp, "never_nl?", RUBY_METHOD_FUNC(re2_regexp_never_nl), 0);
1027
+ rb_define_method(re2_cRegexp, "case_sensitive?", RUBY_METHOD_FUNC(re2_regexp_case_sensitive), 0);
1028
+ rb_define_method(re2_cRegexp, "case_insensitive?", RUBY_METHOD_FUNC(re2_regexp_case_insensitive), 0);
1029
+ rb_define_method(re2_cRegexp, "casefold?", RUBY_METHOD_FUNC(re2_regexp_case_insensitive), 0);
1030
+ rb_define_method(re2_cRegexp, "perl_classes?", RUBY_METHOD_FUNC(re2_regexp_perl_classes), 0);
1031
+ rb_define_method(re2_cRegexp, "word_boundary?", RUBY_METHOD_FUNC(re2_regexp_word_boundary), 0);
1032
+ rb_define_method(re2_cRegexp, "one_line?", RUBY_METHOD_FUNC(re2_regexp_one_line), 0);
1033
+
1034
+ rb_define_module_function(re2_mRE2, "Replace", RUBY_METHOD_FUNC(re2_Replace), 3);
1035
+ rb_define_module_function(re2_mRE2, "GlobalReplace", RUBY_METHOD_FUNC(re2_GlobalReplace), 3);
1036
+ rb_define_module_function(re2_mRE2, "QuoteMeta", RUBY_METHOD_FUNC(re2_QuoteMeta), 1);
1037
+ rb_define_singleton_method(re2_cRegexp, "escape", RUBY_METHOD_FUNC(re2_QuoteMeta), 1);
1038
+ rb_define_singleton_method(re2_cRegexp, "quote", RUBY_METHOD_FUNC(re2_QuoteMeta), 1);
1039
+ rb_define_singleton_method(re2_cRegexp, "compile", RUBY_METHOD_FUNC(rb_class_new_instance), -1);
1040
+
1041
+ rb_define_global_function("RE2", RUBY_METHOD_FUNC(re2_re2), -1);
1041
1042
 
1042
1043
  /* Create the symbols used in options. */
1043
1044
  id_utf8 = rb_intern("utf8");
@@ -1051,5 +1052,10 @@ extern "C" {
1051
1052
  id_perl_classes = rb_intern("perl_classes");
1052
1053
  id_word_boundary = rb_intern("word_boundary");
1053
1054
  id_one_line = rb_intern("one_line");
1055
+
1056
+ #if 0
1057
+ /* Fake so YARD generates the file. */
1058
+ rb_mKernel = rb_define_module("Kernel");
1059
+ #endif
1054
1060
  }
1055
1061
  }
data/test/re2_test.rb CHANGED
@@ -119,6 +119,7 @@ class RE2Test < Test::Unit::TestCase
119
119
  assert_respond_to m, :[]
120
120
  assert_equal r, m.regexp
121
121
  assert_equal text, m.string
122
+ assert !text.frozen?
122
123
  assert m.string.frozen?
123
124
  assert_not_equal m.string.object_id, text.object_id
124
125
  assert_equal '#<RE2::MatchData "123" 1:"123">', m.inspect
metadata CHANGED
@@ -1,13 +1,12 @@
1
1
  --- !ruby/object:Gem::Specification
2
2
  name: re2
3
3
  version: !ruby/object:Gem::Version
4
- hash: 23
5
4
  prerelease: false
6
5
  segments:
7
6
  - 0
7
+ - 1
8
8
  - 0
9
- - 4
10
- version: 0.0.4
9
+ version: 0.1.0
11
10
  platform: ruby
12
11
  authors:
13
12
  - Paul Mucur
@@ -15,7 +14,7 @@ autorequire:
15
14
  bindir: bin
16
15
  cert_chain: []
17
16
 
18
- date: 2010-08-02 00:00:00 +01:00
17
+ date: 2010-08-28 00:00:00 +01:00
19
18
  default_executable:
20
19
  dependencies:
21
20
  - !ruby/object:Gem::Dependency
@@ -26,7 +25,6 @@ dependencies:
26
25
  requirements:
27
26
  - - ">="
28
27
  - !ruby/object:Gem::Version
29
- hash: 3
30
28
  segments:
31
29
  - 0
32
30
  version: "0"
@@ -61,7 +59,6 @@ required_ruby_version: !ruby/object:Gem::Requirement
61
59
  requirements:
62
60
  - - ">="
63
61
  - !ruby/object:Gem::Version
64
- hash: 3
65
62
  segments:
66
63
  - 0
67
64
  version: "0"
@@ -70,7 +67,6 @@ required_rubygems_version: !ruby/object:Gem::Requirement
70
67
  requirements:
71
68
  - - ">="
72
69
  - !ruby/object:Gem::Version
73
- hash: 3
74
70
  segments:
75
71
  - 0
76
72
  version: "0"