ruby-changes:71759
From: Burdette <ko1@a...>
Date: Sun, 17 Apr 2022 05:20:18 +0900 (JST)
Subject: [ruby-changes:71759] 2b4b513ef0 (master): [DOC] Enhanced RDoc for Regexp (#5812)
https://git.ruby-lang.org/ruby.git/commit/?id=2b4b513ef0 From 2b4b513ef046c25c0a8d3d7b10a0566314b27099 Mon Sep 17 00:00:00 2001 From: Burdette Lamar <BurdetteLamar@Y...> Date: Sat, 16 Apr 2022 15:20:03 -0500 Subject: [DOC] Enhanced RDoc for Regexp (#5812) Treats: #fixed_encoding? #hash #== #=~ #match #match? Also, in regexp.rdoc: Changes heading from 'Special Global Variables' to 'Regexp Global Variables'. Add tiny section 'Regexp Interpolation'. --- doc/regexp.rdoc | 10 ++- re.c | 196 ++++++++++++++++++++++++++++++-------------------------- 2 files changed, 114 insertions(+), 92 deletions(-) diff --git a/doc/regexp.rdoc b/doc/regexp.rdoc index b8efc7e3d4..2b6a870026 100644 --- a/doc/regexp.rdoc +++ b/doc/regexp.rdoc @@ -30,6 +30,13 @@ _s_ followed by the letter _t_, so it matches _haystack_, also. https://github.com/ruby/ruby/blob/trunk/doc/regexp.rdoc#L30 Note that any Regexp matching will raise a RuntimeError if timeout is set and exceeded. See "Timeout" section in detail. +== \Regexp Interpolation + +A regexp may contain interpolated strings; trivially: + + foo = 'bar' + /#{foo}/ # => /bar/ + == <tt>=~</tt> and Regexp#match Pattern matching may be achieved by using <tt>=~</tt> operator or Regexp#match @@ -672,9 +679,10 @@ regexp's encoding can be explicitly fixed by supplying https://github.com/ruby/ruby/blob/trunk/doc/regexp.rdoc#L679 # raises Encoding::CompatibilityError: incompatible encoding regexp match # (ISO-8859-1 regexp with UTF-8 string) -== Special Global Variables +== \Regexp Global Variables Pattern matching sets some global variables : + * <tt>$~</tt> is equivalent to Regexp.last_match; * <tt>$&</tt> contains the complete matched text; * <tt>$`</tt> contains string before match; diff --git a/re.c b/re.c index e8a2094beb..b7c2b1fdb3 100644 --- a/re.c +++ b/re.c @@ -1488,31 +1488,31 @@ rb_backref_set_string(VALUE string, long pos, long len) https://github.com/ruby/ruby/blob/trunk/re.c#L1488 /* * call-seq: - * rxp.fixed_encoding? -> true or false - * - * Returns false if rxp is applicable to - * a string with any ASCII compatible encoding. - * Returns true otherwise. - * - * r = /a/ - * r.fixed_encoding? #=> false - * r =~ "\u{6666} a" #=> 2 - * r =~ "\xa1\xa2 a".force_encoding("euc-jp") #=> 2 - * r =~ "abc".force_encoding("euc-jp") #=> 0 - * - * r = /a/u - * r.fixed_encoding? #=> true - * r.encoding #=> #<Encoding:UTF-8> - * r =~ "\u{6666} a" #=> 2 - * r =~ "\xa1\xa2".force_encoding("euc-jp") #=> Encoding::CompatibilityError - * r =~ "abc".force_encoding("euc-jp") #=> 0 - * - * r = /\u{6666}/ - * r.fixed_encoding? #=> true - * r.encoding #=> #<Encoding:UTF-8> - * r =~ "\u{6666} a" #=> 0 - * r =~ "\xa1\xa2".force_encoding("euc-jp") #=> Encoding::CompatibilityError - * r =~ "abc".force_encoding("euc-jp") #=> nil + * fixed_encoding? -> true or false + * + * Returns +false+ if +self+ is applicable to + * a string with any ASCII-compatible encoding; + * otherwise returns +true+: + * + * r = /a/ # => /a/ + * r.fixed_encoding? # => false + * r.match?("\u{6666} a") # => true + * r.match?("\xa1\xa2 a".force_encoding("euc-jp")) # => true + * r.match?("abc".force_encoding("euc-jp")) # => true + * + * r = /a/u # => /a/ + * r.fixed_encoding? # => true + * r.match?("\u{6666} a") # => true + * r.match?("\xa1\xa2".force_encoding("euc-jp")) # Raises exception. + * r.match?("abc".force_encoding("euc-jp")) # => true + * + * r = /\u{6666}/ # => /\u{6666}/ + * r.fixed_encoding? # => true + * r.encoding # => #<Encoding:UTF-8> + * r.match?("\u{6666} a") # => true + * r.match?("\xa1\xa2".force_encoding("euc-jp")) # Raises exception. + * r.match?("abc".force_encoding("euc-jp")) # => false + * */ static VALUE @@ -3116,12 +3116,13 @@ rb_reg_regcomp(VALUE str) https://github.com/ruby/ruby/blob/trunk/re.c#L3116 static st_index_t reg_hash(VALUE re); /* - * call-seq: - * rxp.hash -> integer + * call-seq: + * hash -> integer * - * Produce a hash based on the text and options of this regular expression. + * Returns the integer hash value for +self+. + * + * Related: Object#hash. * - * See also Object#hash. */ VALUE @@ -3145,17 +3146,18 @@ reg_hash(VALUE re) https://github.com/ruby/ruby/blob/trunk/re.c#L3146 /* * call-seq: - * rxp == other_rxp -> true or false - * rxp.eql?(other_rxp) -> true or false + * regexp == object -> true or false + * + * Returns +true+ if +object+ is another \Regexp whose pattern, + * flags, and encoding are the same as +self+, +false+ otherwise: * - * Equality---Two regexps are equal if their patterns are identical, they have - * the same character set code, and their <code>casefold?</code> values are the - * same. + * /foo/ == Regexp.new('foo') # => true + * /foo/ == /foo/i # => false + * /foo/ == Regexp.new('food') # => false + * /foo/ == Regexp.new("abc".force_encoding("euc-jp")) # => false + * + * Regexp#eql? is an alias for Regexp#==. * - * /abc/ == /abc/x #=> false - * /abc/ == /abc/i #=> false - * /abc/ == /abc/u #=> false - * /abc/u == /abc/n #=> false */ VALUE @@ -3264,49 +3266,57 @@ reg_match_pos(VALUE re, VALUE *strp, long pos, VALUE* set_match) https://github.com/ruby/ruby/blob/trunk/re.c#L3266 /* * call-seq: - * rxp =~ str -> integer or nil + * regexp =~ string -> integer or nil + * + * Returns the integer index (in characters) of the first match + * for +self+ and +string+, or +nil+ if none; + * also sets the + * {rdoc-ref:Regexp Global Variables}[rdoc-ref:Regexp@Regexp+Global+Variables]: * - * Match---Matches <i>rxp</i> against <i>str</i>. + * /at/ =~ 'input data' # => 7 + * $~ # => #<MatchData "at"> + * /ax/ =~ 'input data' # => nil + * $~ # => nil * - * /at/ =~ "input data" #=> 7 - * /ax/ =~ "input data" #=> nil + * Assigns named captures to local variables of the same names + * if and only if +self+: * - * If <code>=~</code> is used with a regexp literal with named captures, - * captured strings (or nil) is assigned to local variables named by - * the capture names. + * - Is a regexp literal; + * see {Regexp Literals}[rdoc-ref:literals.rdoc@Regexp+Literals]. + * - Does not contain interpolations; + * see {Regexp Interpolation}[rdoc-ref:Regexp@Regexp+Interpolation]. + * - Is at the left of the expression. * - * /(?<lhs>\w+)\s*=\s*(?<rhs>\w+)/ =~ " x = y " - * p lhs #=> "x" - * p rhs #=> "y" + * Example: * - * If it is not matched, nil is assigned for the variables. + * /(?<lhs>\w+)\s*=\s*(?<rhs>\w+)/ =~ ' x = y ' + * p lhs # => "x" + * p rhs # => "y" * - * /(?<lhs>\w+)\s*=\s*(?<rhs>\w+)/ =~ " x = " - * p lhs #=> nil - * p rhs #=> nil + * Assigns +nil+ if not matched: * - * This assignment is implemented in the Ruby parser. - * The parser detects 'regexp-literal =~ expression' for the assignment. - * The regexp must be a literal without interpolation and placed at left hand side. + * /(?<lhs>\w+)\s*=\s*(?<rhs>\w+)/ =~ ' x = ' + * p lhs # => nil + * p rhs # => nil * - * The assignment does not occur if the regexp is not a literal. + * Does not make local variable assignments if +self+ is not a regexp literal: * - * re = /(?<lhs>\w+)\s*=\s*(?<rhs>\w+)/ - * re =~ " x = y " - * p lhs # undefined local variable - * p rhs # undefined local variable + * r = /(?<foo>\w+)\s*=\s*(?<foo>\w+)/ + * r =~ ' x = y ' + * p foo # Undefined local variable + * p bar # Undefined local variable * - * A regexp interpolation, <code>#{}</code>, also disables - * the assignment. + * The assignment does not occur if the regexp is not at the left: * - * rhs_pat = /(?<rhs>\w+)/ - * /(?<lhs>\w+)\s*=\s*#{rhs_pat}/ =~ "x = y" - * p lhs # undefined local variable + * ' x = y ' =~ /(?<foo>\w+)\s*=\s*(?<foo>\w+)/ + * p foo, foo # Undefined local variables * - * The assignment does not occur if the regexp is placed at the right hand side. + * A regexp interpolation, <tt>#{}</tt>, also disables + * the assignment: * - * " x = y " =~ /(?<lhs>\w+)\s*=\s*(?<rhs>\w+)/ - * p lhs, rhs # undefined local variable + * r = /(?<foo>\w+)/ + * /(?<foo>\w+)\s*=\s*#{r}/ =~ 'x = y' + * p foo # Undefined local variable * */ @@ -3388,34 +3398,38 @@ rb_reg_match2(VALUE re) https://github.com/ruby/ruby/blob/trunk/re.c#L3398 /* * call-seq: - * rxp.match(str, pos=0) -> matchdata or nil - * rxp.match(str, pos=0) {|match| block } -> obj + * match(string, offset = 0) -> matchdata or nil + * match(string, offset = 0) {|matchdata| ... } -> object * - * Returns a MatchData object describing the match, or - * <code>nil</code> if there was no match. This is equivalent to - * retrieving the value of the special variable <code>$~</code> - * following a normal match. If the second parameter is present, it - * specifies the position in the string to begin the search. + * With no block given, returns the MatchData obj (... truncated) -- ML: ruby-changes@q... Info: http://www.atdot.net/~ko1/quickml/