[前][次][番号順一覧][スレッド一覧]

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/

[前][次][番号順一覧][スレッド一覧]