ruby-changes:71769
From: Burdette <ko1@a...>
Date: Tue, 19 Apr 2022 00:46:00 +0900 (JST)
Subject: [ruby-changes:71769] 51ea67698e (master): [DOC] Enhanced RDoc for Regexp (#5815)
https://git.ruby-lang.org/ruby.git/commit/?id=51ea67698e From 51ea67698e36f9a0a3a3aa9a4566b6bec4b41bd3 Mon Sep 17 00:00:00 2001 From: Burdette Lamar <BurdetteLamar@Y...> Date: Mon, 18 Apr 2022 10:45:29 -0500 Subject: [DOC] Enhanced RDoc for Regexp (#5815) Treats: ::new ::escape ::try_convert ::union ::last_match --- re.c | 236 +++++++++++++++++++++++++++++++++++++++---------------------------- 1 file changed, 136 insertions(+), 100 deletions(-) diff --git a/re.c b/re.c index b7c2b1fdb3..5dda7f3b5d 100644 --- a/re.c +++ b/re.c @@ -3331,23 +3331,22 @@ rb_reg_match(VALUE re, VALUE str) https://github.com/ruby/ruby/blob/trunk/re.c#L3331 /* * call-seq: - * rxp === str -> true or false + * regexp === string -> true or false * - * Case Equality---Used in case statements. + * Returns +true+ if +self+ finds a match in +string+: * - * a = "HELLO" - * case a - * when /\A[a-z]*\z/; print "Lower case\n" - * when /\A[A-Z]*\z/; print "Upper case\n" - * else; print "Mixed case\n" - * end - * #=> "Upper case" + * /^[a-z]*$/ === 'HELLO' # => false + * /^[A-Z]*$/ === 'HELLO' # => true * - * Following a regular expression literal with the #=== operator allows you to - * compare against a String. + * This method is called in case statements: + * + * s = 'HELLO' + * case s + * when /\A[a-z]*\z/; print "Lower case\n" + * when /\A[A-Z]*\z/; print "Upper case\n" + * else print "Mixed case\n" + * end # => "Upper case" * - * /^[a-z]*$/ === "HELLO" #=> false - * /^[A-Z]*$/ === "HELLO" #=> true */ static VALUE @@ -3367,13 +3366,13 @@ rb_reg_eqq(VALUE re, VALUE str) https://github.com/ruby/ruby/blob/trunk/re.c#L3366 /* * call-seq: - * ~ rxp -> integer or nil + * ~ rxp -> integer or nil + * + * Equivalent to <tt><i>rxp</i> =~ $_</tt>: * - * Match---Matches <i>rxp</i> against the contents of <code>$_</code>. - * Equivalent to <code><i>rxp</i> =~ $_</code>. + * $_ = "input data" + * ~ /at/ # => 7 * - * $_ = "input data" - * ~ /at/ #=> 7 */ VALUE @@ -3540,28 +3539,38 @@ rb_reg_match_p(VALUE re, VALUE str, long pos) https://github.com/ruby/ruby/blob/trunk/re.c#L3539 /* * call-seq: - * Regexp.new(string, [options], timeout: nil) -> regexp - * Regexp.new(regexp) -> regexp - * Regexp.compile(string, [options], timeout: nil) -> regexp - * Regexp.compile(regexp) -> regexp - * - * Constructs a new regular expression from +pattern+, which can be either a - * String or a Regexp (in which case that regexp's options are propagated), - * and new options may not be specified (a change as of Ruby 1.8). - * - * If +options+ is an Integer, it should be one or more of the constants - * Regexp::EXTENDED, Regexp::IGNORECASE, and Regexp::MULTILINE, - * <em>or</em>-ed together. Otherwise, if +options+ is not - * +nil+ or +false+, the regexp will be case insensitive. - * - * r1 = Regexp.new('^a-z+:\\s+\w+') #=> /^a-z+:\s+\w+/ - * r2 = Regexp.new('cat', true) #=> /cat/i - * r3 = Regexp.new(r2) #=> /cat/i - * r4 = Regexp.new('dog', Regexp::EXTENDED | Regexp::IGNORECASE) #=> /dog/ix - * - * +timeout+ keyword sets per-object timeout configuration. - * If this is not set, the global timeout configuration set by Regexp.timeout= - * is used. + * Regexp.new(string, options = 0, timeout: nil) -> regexp + * Regexp.new(regexp) -> regexp + * + * With argument +string+ given, returns a new regexp with the given string + * and options: + * + * r = Regexp.new('foo') # => /foo/ + * r.source # => "foo" + * r.options # => 0 + * + * Optional argument +options+ is one of the following: + * + * - The logical OR of one or more of the constants + * Regexp::EXTENDED, Regexp::IGNORECASE, and Regexp::MULTILINE: + * + * Regexp.new('foo', Regexp::IGNORECASE) # => /foo/i + * Regexp.new('foo', Regexp::EXTENDED) # => /foo/x + * Regexp.new('foo', Regexp::MULTILINE) # => /foo/m + * flags = Regexp::IGNORECASE | Regexp::EXTENDED | Regexp::MULTILINE + * Regexp.new('foo', flags) # => /foo/mix + * + * - +nil+ or +false+, which is ignored. + * + * If optional keyword argument +timeout+ is given, + * its integer value overrides the timeout interval for the class, + * Regexp.timeout. + * + * With argument +regexp+ given, returns a new regexp + * source, options, and timeout are the same as +self+. + * + * Regexp.compile is an alias for Regexp.new. + * */ static VALUE @@ -3726,15 +3735,19 @@ rb_reg_quote(VALUE str) https://github.com/ruby/ruby/blob/trunk/re.c#L3735 /* * call-seq: - * Regexp.escape(str) -> string - * Regexp.quote(str) -> string + * Regexp.escape(string) -> new_string + * + * Returns a new string that escapes any characters + * that have special meaning in a regular expression: + * + * s = Regexp.escape('\*?{}.') # => "\\\\\\*\\?\\{\\}\\." + * + * For any string +s+, this call returns a MatchData object: * - * Escapes any characters that would have special meaning in a regular - * expression. Returns a new escaped string with the same or compatible - * encoding. For any string, - * <code>Regexp.new(Regexp.escape(<i>str</i>))=~<i>str</i></code> will be true. + * r = Regexp.new(Regexp.escape(s)) # => /\\\\\\\*\\\?\\\{\\\}\\\./ + * r.match(s) # => #<MatchData "\\\\\\*\\?\\{\\}\\."> * - * Regexp.escape('\*?{}.') #=> \\\*\?\{\}\. + * Regexp.quote is an alias for Regexp.escape. * */ @@ -3764,19 +3777,20 @@ rb_check_regexp_type(VALUE re) https://github.com/ruby/ruby/blob/trunk/re.c#L3777 /* * call-seq: - * Regexp.try_convert(obj) -> re or nil + * Regexp.try_convert(object) -> regexp or nil * - * Try to convert <i>obj</i> into a Regexp, using to_regexp method. - * Returns converted regexp or nil if <i>obj</i> cannot be converted - * for any reason. + * Returns +object+ if it is a regexp: * - * Regexp.try_convert(/re/) #=> /re/ - * Regexp.try_convert("re") #=> nil + * Regexp.try_convert(/re/) # => /re/ * - * o = Object.new - * Regexp.try_convert(o) #=> nil - * def o.to_regexp() /foo/ end - * Regexp.try_convert(o) #=> /foo/ + * Otherwise if +object+ responds to <tt>:to_regexp</tt>, + * calls <tt>object.to_regexp</tt> and returns the result. + * + * Returns +nil+ if +object+ does not respond to <tt>:to_regexp</tt>. + * + * Regexp.try_convert('re') # => nil + * + * Raises an exception unless <tt>object.to_regexp</tt> returns a regexp. * */ static VALUE @@ -3901,25 +3915,37 @@ rb_reg_s_union(VALUE self, VALUE args0) https://github.com/ruby/ruby/blob/trunk/re.c#L3915 /* * call-seq: - * Regexp.union(pat1, pat2, ...) -> new_regexp - * Regexp.union(pats_ary) -> new_regexp - * - * Return a Regexp object that is the union of the given - * <em>pattern</em>s, i.e., will match any of its parts. The - * <em>pattern</em>s can be Regexp objects, in which case their - * options will be preserved, or Strings. If no patterns are given, - * returns <code>/(?!)/</code>. The behavior is unspecified if any - * given <em>pattern</em> contains capture. - * - * Regexp.union #=> /(?!)/ - * Regexp.union("penzance") #=> /penzance/ - * Regexp.union("a+b*c") #=> /a\+b\*c/ - * Regexp.union("skiing", "sledding") #=> /skiing|sledding/ - * Regexp.union(["skiing", "sledding"]) #=> /skiing|sledding/ - * Regexp.union(/dogs/, /cats/i) #=> /(?-mix:dogs)|(?i-mx:cats)/ - * - * Note: the arguments for ::union will try to be converted into a regular - * expression literal via #to_regexp. + * Regexp.union(*patterns) -> regexp + * Regexp.union(array_of_patterns) -> regexp + * + * Returns a new regexp that is the union of the given patterns: + * + * r = Regexp.union(%w[cat dog]) # => /cat|dog/ + * r.match('cat') # => #<MatchData "cat"> + * r.match('dog') # => #<MatchData "dog"> + * r.match('cog') # => nil + * + * For each pattern that is a string, <tt>Regexp.new(pattern)</tt> is used: + * + * Regexp.union('penzance') # => /penzance/ + * Regexp.union('a+b*c') # => /a\+b\*c/ + * Regexp.union('skiing', 'sledding') # => /skiing|sledding/ + * Regexp.union(['skiing', 'sledding']) # => /skiing|sledding/ + * + * For each pattern that is a regexp, it is used as is, + * including its flags: + * + * Regexp.union(/foo/i, /bar/m, /baz/x) + * # => /(?i-mx:foo)|(?m-ix:bar)|(?x-mi:baz)/ + * Regexp.union([/foo/i, /bar/m, /baz/x]) + * # => /(?i-mx:foo)|(?m-ix:bar)|(?x-mi:baz)/ + * + * With no arguments, returns <tt>/(?!)/</tt>: + * + * Regexp.union # => /(?!)/ + * + * If any regexp pattern contains captures, the behavior is unspecified. + * */ static VALUE rb_reg_s_union_m(VALUE self, VALUE args) @@ -4106,30 +4132,40 @@ match_setter(VALUE val, ID _x, VALUE *_y) https://github.com/ruby/ruby/blob/trunk/re.c#L4132 /* * call-seq: - * Regexp.last_match -> matchdata - * Regexp.last_match(n) -> str - * - * The first form returns the MatchData object generated by the - * last successful pattern match. Equivalent to reading the special global - * variable <code>$~</code> (see Special global variables in Regexp for - * details). - * - * The second form returns the <i>n</i>th field in this MatchData object. - * _n_ can be a string or symbol to reference a named capture. - * - * Note that the last_match is local to the thread and method scope of the - * method that did the pattern match. - * - * /c(.)t/ =~ 'cat' #=> 0 - * Regexp.last_match #=> #<MatchData "cat" 1:"a"> - * Regexp.last_match(0) #=> "cat" - * Regexp.last_match(1) #=> "a" - * (... truncated) -- ML: ruby-changes@q... Info: http://www.atdot.net/~ko1/quickml/