From 2b4b513ef046c25c0a8d3d7b10a0566314b27099 Mon Sep 17 00:00:00 2001 From: Burdette Lamar Date: Sat, 16 Apr 2022 15:20:03 -0500 Subject: [PATCH] [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 | 192 ++++++++++++++++++++++++++---------------------- 2 files changed, 112 insertions(+), 90 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. 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/ + == =~ and Regexp#match Pattern matching may be achieved by using =~ operator or Regexp#match @@ -672,9 +679,10 @@ regexp's encoding can be explicitly fixed by supplying # 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 : + * $~ is equivalent to Regexp.last_match; * $& contains the complete matched text; * $` 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) /* * call-seq: - * rxp.fixed_encoding? -> true or false + * fixed_encoding? -> true or false * - * Returns false if rxp is applicable to - * a string with any ASCII compatible encoding. - * Returns true otherwise. + * Returns +false+ if +self+ is applicable to + * a string with any ASCII-compatible encoding; + * otherwise returns +true+: * - * 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/ # => /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 - * r.fixed_encoding? #=> true - * r.encoding #=> # - * r =~ "\u{6666} a" #=> 2 - * r =~ "\xa1\xa2".force_encoding("euc-jp") #=> Encoding::CompatibilityError - * r =~ "abc".force_encoding("euc-jp") #=> 0 + * 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 # => # + * r.match?("\u{6666} a") # => true + * r.match?("\xa1\xa2".force_encoding("euc-jp")) # Raises exception. + * r.match?("abc".force_encoding("euc-jp")) # => false * - * r = /\u{6666}/ - * r.fixed_encoding? #=> true - * r.encoding #=> # - * r =~ "\u{6666} a" #=> 0 - * r =~ "\xa1\xa2".force_encoding("euc-jp") #=> Encoding::CompatibilityError - * r =~ "abc".force_encoding("euc-jp") #=> nil */ static VALUE @@ -3116,12 +3116,13 @@ rb_reg_regcomp(VALUE str) 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) /* * call-seq: - * rxp == other_rxp -> true or false - * rxp.eql?(other_rxp) -> true or false + * regexp == object -> true or false * - * Equality---Two regexps are equal if their patterns are identical, they have - * the same character set code, and their casefold? values are the - * same. + * Returns +true+ if +object+ is another \Regexp whose pattern, + * flags, and encoding are the same as +self+, +false+ otherwise: + * + * /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) /* * call-seq: - * rxp =~ str -> integer or nil + * regexp =~ string -> integer or nil * - * Match---Matches rxp against str. + * 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]: * - * /at/ =~ "input data" #=> 7 - * /ax/ =~ "input data" #=> nil + * /at/ =~ 'input data' # => 7 + * $~ # => # + * /ax/ =~ 'input data' # => nil + * $~ # => nil * - * If =~ is used with a regexp literal with named captures, - * captured strings (or nil) is assigned to local variables named by - * the capture names. + * Assigns named captures to local variables of the same names + * if and only if +self+: * - * /(?\w+)\s*=\s*(?\w+)/ =~ " x = y " - * p lhs #=> "x" - * p rhs #=> "y" + * - 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. * - * If it is not matched, nil is assigned for the variables. + * Example: * - * /(?\w+)\s*=\s*(?\w+)/ =~ " x = " - * p lhs #=> nil - * p rhs #=> nil + * /(?\w+)\s*=\s*(?\w+)/ =~ ' x = y ' + * p lhs # => "x" + * p rhs # => "y" * - * 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. + * Assigns +nil+ if not matched: * - * The assignment does not occur if the regexp is not a literal. + * /(?\w+)\s*=\s*(?\w+)/ =~ ' x = ' + * p lhs # => nil + * p rhs # => nil * - * re = /(?\w+)\s*=\s*(?\w+)/ - * re =~ " x = y " - * p lhs # undefined local variable - * p rhs # undefined local variable + * Does not make local variable assignments if +self+ is not a regexp literal: * - * A regexp interpolation, #{}, also disables - * the assignment. + * r = /(?\w+)\s*=\s*(?\w+)/ + * r =~ ' x = y ' + * p foo # Undefined local variable + * p bar # Undefined local variable * - * rhs_pat = /(?\w+)/ - * /(?\w+)\s*=\s*#{rhs_pat}/ =~ "x = y" - * p lhs # undefined local variable + * The assignment does not occur if the regexp is not at the left: * - * The assignment does not occur if the regexp is placed at the right hand side. + * ' x = y ' =~ /(?\w+)\s*=\s*(?\w+)/ + * p foo, foo # Undefined local variables * - * " x = y " =~ /(?\w+)\s*=\s*(?\w+)/ - * p lhs, rhs # undefined local variable + * A regexp interpolation, #{}, also disables + * the assignment: + * + * r = /(?\w+)/ + * /(?\w+)\s*=\s*#{r}/ =~ 'x = y' + * p foo # Undefined local variable * */ @@ -3388,34 +3398,38 @@ rb_reg_match2(VALUE re) /* * 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 - * nil if there was no match. This is equivalent to - * retrieving the value of the special variable $~ - * 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 object + * that describes the match, if any, or +nil+ if none; + * the search begins at the given byte +offset+ in +self+: + * + * /abra/.match('abracadabra') # => # + * /abra/.match('abracadabra', 4) # => # + * /abra/.match('abracadabra', 8) # => nil + * /abra/.match('abracadabra', 800) # => nil + * + * With a block given, calls the block if and only if a match is found; + * returns the block's value: + * + * /abra/.match('abracadabra') {|matchdata| p matchdata } + * # => # + * /abra/.match('abracadabra', 4) {|matchdata| p matchdata } + * # => # + * /abra/.match('abracadabra', 8) {|matchdata| p matchdata } + * # => nil + * /abra/.match('abracadabra', 8) {|marchdata| fail 'Cannot happen' } + * # => nil + * + * Output (from the first two blocks above): + * + * # + * # * * /(.)(.)(.)/.match("abc")[2] #=> "b" * /(.)(.)/.match("abc", 1)[2] #=> "c" * - * If a block is given, invoke the block with MatchData if match succeed, so - * that you can write - * - * /M(.*)/.match("Matz") do |m| - * puts m[0] - * puts m[1] - * end - * - * instead of - * - * if m = /M(.*)/.match("Matz") - * puts m[0] - * puts m[1] - * end - * - * The return value is a value from block execution in this case. */ static VALUE @@ -3445,8 +3459,8 @@ rb_reg_match_m(int argc, VALUE *argv, VALUE re) /* * call-seq: - * rxp.match?(str) -> true or false - * rxp.match?(str, pos=0) -> true or false + * match?(string) -> true or false + * match?(string, offset = 0) -> true or false * * Returns true or false to indicate whether the * regexp is matched or not without updating $~ and other related variables.