From 51ea67698e36f9a0a3a3aa9a4566b6bec4b41bd3 Mon Sep 17 00:00:00 2001 From: Burdette Lamar 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) /* * 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) /* * call-seq: - * ~ rxp -> integer or nil + * ~ rxp -> integer or nil + * + * Equivalent to rxp =~ $_: * - * Match---Matches rxp against the contents of $_. - * Equivalent to rxp =~ $_. + * $_ = "input data" + * ~ /at/ # => 7 * - * $_ = "input data" - * ~ /at/ #=> 7 */ VALUE @@ -3540,28 +3539,38 @@ rb_reg_match_p(VALUE re, VALUE str, long pos) /* * 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, - * or-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) /* * 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, - * Regexp.new(Regexp.escape(str))=~str will be true. + * r = Regexp.new(Regexp.escape(s)) # => /\\\\\\\*\\\?\\\{\\\}\\\./ + * r.match(s) # => # * - * Regexp.escape('\*?{}.') #=> \\\*\?\{\}\. + * Regexp.quote is an alias for Regexp.escape. * */ @@ -3764,19 +3777,20 @@ rb_check_regexp_type(VALUE re) /* * call-seq: - * Regexp.try_convert(obj) -> re or nil + * Regexp.try_convert(object) -> regexp or nil * - * Try to convert obj into a Regexp, using to_regexp method. - * Returns converted regexp or nil if obj 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 :to_regexp, + * calls object.to_regexp and returns the result. + * + * Returns +nil+ if +object+ does not respond to :to_regexp. + * + * Regexp.try_convert('re') # => nil + * + * Raises an exception unless object.to_regexp returns a regexp. * */ static VALUE @@ -3901,25 +3915,37 @@ rb_reg_s_union(VALUE self, VALUE args0) /* * 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 - * patterns, i.e., will match any of its parts. The - * patterns can be Regexp objects, in which case their - * options will be preserved, or Strings. If no patterns are given, - * returns /(?!)/. The behavior is unspecified if any - * given pattern 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') # => # + * r.match('dog') # => # + * r.match('cog') # => nil + * + * For each pattern that is a string, Regexp.new(pattern) 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 /(?!)/: + * + * 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) /* * 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 $~ (see Special global variables in Regexp for - * details). - * - * The second form returns the nth 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 #=> # - * Regexp.last_match(0) #=> "cat" - * Regexp.last_match(1) #=> "a" - * Regexp.last_match(2) #=> nil - * - * /(?\w+)\s*=\s*(?\w+)/ =~ "var = val" - * Regexp.last_match #=> # - * Regexp.last_match(:lhs) #=> "var" - * Regexp.last_match(:rhs) #=> "val" + * Regexp.last_match -> matchdata or nil + * Regexp.last_match(n) -> string or nil + * Regexp.last_match(name) -> string or nil + * + * With no argument, returns the value of $!, + * which is the result of the most recent pattern match + * (see {Regexp Global Variables}[rdoc-ref:Regexp@Regexp+Global+Variables]): + * + * /c(.)t/ =~ 'cat' # => 0 + * Regexp.last_match # => # + * /a/ =~ 'foo' # => nil + * Regexp.last_match # => nil + * + * With non-negative integer argument +n+, returns the _n_th field in the + * matchdata, if any, or nil if none: + * + * /c(.)t/ =~ 'cat' # => 0 + * Regexp.last_match(0) # => "cat" + * Regexp.last_match(1) # => "a" + * Regexp.last_match(2) # => nil + * + * With negative integer argument +n+, counts backwards from the last field: + * + * Regexp.last_match(-1) # => "a" + * + * With string or symbol argument +name+, + * returns the string value for the named capture, if any: + * + * /(?\w+)\s*=\s*(?\w+)/ =~ 'var = val' + * Regexp.last_match # => # + * Regexp.last_match(:lhs) # => "var" + * Regexp.last_match('rhs') # => "val" + * Regexp.last_match('foo') # Raises IndexError. + * */ static VALUE -- cgit v1.2.3